Skip to content
Connect an agent
Use the server

Local usage counts and sharing

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

QuestionAnswer
Is anything counted or sent by default?No. With nothing set, the local server reads no file but your repository settings (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-beta.10 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_USAGEWhat happens
Unset, empty, or anything elseOff. The server behaves exactly as it always has.
localThe server counts its tool calls in a file on your device and sends nothing.
shareThe 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-beta.10"      ],      "env": {        "PLOTWORK_USAGE": "local"      }    }  }}

In a shell, run PLOTWORK_USAGE=local npx -y @buun_group/plotwork-mcp@0.1.0-beta.10. 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:

PartValues
The toolOne of the tools the local server offers, such as draw_diagram or validate_diagram.
The kind of diagramOne 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 endedok (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        }      ]    }  ]}
FieldWhat it is
idA 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.
clientThe package version, your operating system family (linux, darwin, win32, or other), and your Node major version.
countsThe 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 says the same in full.

4. See what it holds

These commands are for you. They never send anything.

CommandWhat it shows
npx -y @buun_group/plotwork-mcp@0.1.0-beta.10 usageThe 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-beta.10 usage previewThe 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-beta.10 usage resetDeletes 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-beta.10 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 (opens in a new tab) with it. Totals sent under an earlier month's identifier cannot be tied to you, and are deleted as they age out.

See also

DocWhy
MCP serverWhat the local and hosted servers are and how they differ
Connecting an agentStarting the local server from an agent client
Privacy policyThe full statement of what Plotwork collects, including usage totals