Plotwork MCP server

The Plotwork diagram tools as a local MCP (Model Context Protocol) server. An AI agent uses it to read the diagram language, validate source, check an outline, and render twenty-nine kinds of diagram, from flow, sequence, and database to Gantt, state, mind map, and treemap as SVG. It runs on your machine over standard input and output.

TL;DR

Install

Nothing is installed globally. Your client starts the server with npx, and npx downloads this package on first use.

Claude Code

claude mcp add plotwork -- npx -y @buun_group/plotwork-mcp

Then run /mcp in Claude Code and check that plotwork is connected and lists the Plotwork tools.

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "plotwork": {
      "command": "npx",
      "args": ["-y", "@buun_group/plotwork-mcp"]
    }
  }
}

VS Code

Add this to .vscode/mcp.json:

{
  "servers": {
    "plotwork": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@buun_group/plotwork-mcp"]
    }
  }
}

Claude Desktop

Add this to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "plotwork": {
      "command": "npx",
      "args": ["-y", "@buun_group/plotwork-mcp"]
    }
  }
}

Other clients

Any client that starts an MCP server as a local process takes the same two parts: the command npx and the arguments -y @buun_group/plotwork-mcp.

Open and self-hosted models

A model with a small context (an open model on Ollama, LM Studio, vLLM, or llama.cpp) does better with fewer tools. Add --tools core to the arguments, or set PLOTWORK_TOOLS=core, and the server lists only its eight workflow tools with short descriptions: about 1,700 tokens instead of about 17,500. The tools answer the same. See Use Plotwork with open and self-hosted models.

Check it by hand

npx -y @buun_group/plotwork-mcp --version
npx -y @buun_group/plotwork-mcp --help

Run with no arguments, plotwork-mcp waits for an MCP client on standard input. Standard output carries only protocol messages. One log line per tool call goes to standard error, with the tool, the outcome, the duration, and the size of the arguments. The contents of the arguments are never logged.

Usage counts (off unless you turn them on)

By default the package counts nothing and keeps no file. You can ask it to count how often each tool is used on your own machine, and, separately, to send pseudonymous daily totals to Plotwork so the project can see which tools matter. Both are off until you set PLOTWORK_USAGE in the env block of your client or in your shell. There is no config file, so nothing is switched on out of sight.

Only counts are kept. A count is a tool name, the diagram kind the source declared (flow, sequence, schema, or none), how the call ended (ok, rejected, or error), and a number, for each UTC day. Diagram source, arguments, names, file paths, error messages, your host name and user name, and the time of day are never counted or sent.

What share sends is a small JSON body with those counts, a pseudonym for the month (a keyed hash that changes every month, so Plotwork can count active installs in a month but cannot follow one from month to month), the package version, your operating system family, and the Node major version. It carries no cookie, no account, and no key. It never sends today, never follows a redirect, gives up after three seconds, and fails silently.

You can look at all of it before you decide:

npx -y @buun_group/plotwork-mcp usage            # the setting, the counts of the last 30 days, and the next send
npx -y @buun_group/plotwork-mcp usage preview    # the exact request a send would post, or "nothing to send"
npx -y @buun_group/plotwork-mcp usage reset      # delete the file, with its secret and every count

These commands never touch the network.

The hosted server

The hosted server runs the same tools at https://mcp.plotwork.dev. Use it when a client cannot start a local process, or when you want one shared endpoint. It is not part of this package, and it asks for a credential.

The documentation has the exact settings for each client.

License

@buun_group/plotwork-mcp is licensed under the MIT licence. The text is in the file LICENSE.

The single file plotwork-mcp.mjs also contains code and data that other people wrote: the MCP SDK, the zod validation library, the ELK layout engine, icon artwork, and font measurements. Each keeps its own licence. THIRD-PARTY-NOTICES.md lists every one with its version, copyright, and the full licence text. The MIT licence of this package does not replace those licences.

The package includes the official architecture icons of AWS, Microsoft Azure, Google Cloud, unmodified. They belong to their owners and are not covered by the MIT licence. Their terms and the trademark notice are in THIRD-PARTY-NOTICES.md.

About this repository

This repository holds the built package that is published to npm, updated by an automated release. A change here is replaced by the next release, so open an issue instead of a pull request. Releases are immutable: a published version is never changed, and a fix is a new version.

Each release carries checksums.txt with the SHA-256 of every file in the package, including LICENSE and THIRD-PARTY-NOTICES.md. To check a download:

sha256sum --check checksums.txt

See also