# Local usage counts and sharing

> Page: https://docs.plotwork.dev/mcp/usage. Index of every page: https://docs.plotwork.dev/llms.txt

Count how you use the local MCP server on your own machine, and choose whether to share pseudonymous daily totals with Plotwork. Both are off by default.

## TL;DR

| Question | Answer |
|---|---|
| Is anything counted or sent by default? | No. With nothing set, the local server reads no file but your [repository settings](https://docs.plotwork.dev/repository-settings.md) (`plotwork.config.json`, if you have one), writes no file, and makes no network request. The one exception is `read_diagram` given the link of a Plotwork picture, which fetches that link and sends nothing else. |
| How do I turn it on? | Set the environment variable `PLOTWORK_USAGE` to `local` or `share`, in your agent client's `env` block or in your shell. |
| What does `local` do? | It counts your tool calls in one file on your device. Nothing leaves the device. |
| What does `share` do? | It counts as `local` does, and once a day sends totals for finished days to Plotwork. |
| What is sent? | Counts by tool, diagram kind, and outcome, a random identifier that changes every month, the package version, your operating system family, and your Node major version. Never diagram text. |
| How do I see what it holds? | Run `npx -y @buun_group/plotwork-mcp@0.1.0 usage`. Run `usage preview` for the exact request. Neither sends anything. |
| How do I stop and delete? | Unset the variable, then run `usage reset`. |

## 1. Turn it on

The setting is an environment variable, so it lives where you can see it. There is no config file.

| Value of `PLOTWORK_USAGE` | What happens |
|---|---|
| Unset, empty, or anything else | Off. The server behaves exactly as it always has. |
| `local` | The server counts its tool calls in a file on your device and sends nothing. |
| `share` | The server counts, and also sends totals to Plotwork once a day. |

Only the exact lowercase words `local` and `share` turn anything on. Setting `DO_NOT_TRACK` to `1` or `true` stops the server from ever sending, whatever `PLOTWORK_USAGE` says, so `share` then behaves as `local`.

Most agent clients start the server for you, so set the variable in the client's configuration:

```json
{
  "mcpServers": {
    "plotwork": {
      "command": "npx",
      "args": [
        "-y",
        "@buun_group/plotwork-mcp@0.1.0"
      ],
      "env": {
        "PLOTWORK_USAGE": "local"
      }
    }
  }
}
```

In a shell, run `PLOTWORK_USAGE=local npx -y @buun_group/plotwork-mcp@0.1.0`. The setting is read once, when the server starts, so restart the server after you change it.

## 2. What is counted

A count has three parts, and each comes from a short fixed list:

| Part | Values |
|---|---|
| The tool | One of the tools the local server offers, such as `draw_diagram` or `validate_diagram`. |
| The kind of diagram | One of `flow`, `sequence`, `schema`, `git`, `gantt`, `class`, `state`, `timeline`, `journey`, `mindmap`, `treemap`, `pie`, `quadrant`, `layers`, `c4`, `matrix`, `sankey`, `xychart`, `tree`, or `swimlane`, taken from the first word of the source, or `none` for a call with no source. |
| How the call ended | `ok` (it produced its answer), `rejected` (your input made that impossible, such as source with errors), or `error` (the server failed). |

The server adds one to the matching count for the day, in UTC. It never records the source, a tool's arguments or results, a name, a path, or an error message.

The counts live in `usage.json` in a `.plotwork` folder in your home folder. Set `PLOTWORK_HOME` to use another folder. The file is readable only by you where your system allows it, holds the last 90 days, and also holds a random secret that never leaves your device. Counting never slows or fails a tool call.

## 3. What sharing sends

In `share` mode the server sends once a day, about 5 seconds after it starts and then every 24 hours, to `https://api.plotwork.dev/telemetry/usage`. It sends only days that are over and not yet sent, never today. A failure is silent, and it tries again the next day.

```json
{
  "schema": 1,
  "client": {
    "name": "plotwork-mcp",
    "version": "1.4.2",
    "os": "linux",
    "node": 22
  },
  "days": [
    {
      "day": "2026-10-08",
      "id": "3f9a1c0e5b7d42a8e6c1f0d9b2a47e65",
      "counts": [
        {
          "tool": "draw_diagram",
          "kind": "flow",
          "outcome": "ok",
          "count": 12
        }
      ]
    }
  ]
}
```

| Field | What it is |
|---|---|
| `id` | A random identifier made on your device from the secret in the file and the month. It changes every month, so Plotwork can count how many installs were active in a month but cannot follow one install from month to month. The secret is never sent. |
| `client` | The package version, your operating system family (`linux`, `darwin`, `win32`, or `other`), and your Node major version. |
| `counts` | The counts from section 2, for that day. |

The request carries no cookie, account, or key. The package chooses only a content type and a user agent that names the package and its version. It never follows a redirect, and it gives up after 3 seconds.

Never sent: diagram text, tool arguments or results, names, folders, file paths, error messages, your user name, your host name, environment variables, and the time of day.

On Plotwork's side, the totals go into a table of their own that is never used for limits, billing, or anything about an account. Plotwork stores no address, header, or cookie with them. The route is rate limited, and Cloudflare's rate-limiting service holds your address as a counter key for 60 seconds. Rows are deleted after 400 days. The [privacy policy](https://docs.plotwork.dev/privacy-policy.md#usage-totals) says the same in full.

## 4. See what it holds

These commands are for you. They never send anything.

| Command | What it shows |
|---|---|
| `npx -y @buun_group/plotwork-mcp@0.1.0 usage` | The mode and which setting chose it, the file and whether it exists, your counts for the last 30 days, your current identifier, and when the next send is due. |
| `npx -y @buun_group/plotwork-mcp@0.1.0 usage preview` | The exact request the next send would post, or a note that there is nothing to send. It works in any mode. |
| `npx -y @buun_group/plotwork-mcp@0.1.0 usage reset` | Deletes the file, which removes your secret and every count. |

## 5. Stop and delete

1. Remove `PLOTWORK_USAGE` from your client's configuration, or set it to `off`, and restart the server.
2. Run `npx -y @buun_group/plotwork-mcp@0.1.0 usage reset` to delete the file on your device.
3. To have totals already sent deleted, run `usage` to read your current identifier and write to legal@buungroup.com with it. Totals sent under an earlier month's identifier cannot be tied to you, and are deleted as they age out.

## See also

| Doc | Why |
|---|---|
| [MCP server](https://docs.plotwork.dev/mcp/overview.md) | What the local and hosted servers are and how they differ |
| [Connecting an agent](https://docs.plotwork.dev/mcp/connect.md) | Starting the local server from an agent client |
| [Privacy policy](https://docs.plotwork.dev/privacy-policy.md) | The full statement of what Plotwork collects, including usage totals |