The local MCP server

koboyo mcp runs an MCP server on your own machine, so a coding agent can write diagram code, look at the picture, and save the image into your project. It is free, needs no account or key, and nothing leaves your machine except icon downloads from koboyo.com.

It is a different server from the hosted MCP server, which saves diagrams to your Koboyo boards and is part of Koboyo Pro. You can use both.

Set it up in one step#

npx koboyo setup

This finds the coding agents on your machine (Claude Code, Codex, Cursor, VS Code and Windsurf) and, for each one:

installs the koboyo skill, which tells the agent when to draw, how to write each kind of diagram, how to check the picture, and how to hand a diagram to you for edits;
adds the local MCP server, with the agent's own command where it has one.

It shows what it will change and asks first. A config file it edits is copied to <file>.koboyo-backup before the change, and anything you set up yourself under the name koboyo is left as it is.

option	what it does
`--dry-run`	Shows the plan and changes nothing
`--yes`	Goes ahead without asking, for scripts
`--agent <names>`	Sets up only these agents, comma-separated, even ones it did not find
`--project`	Sets up the folder you are in, so your team gets it through the repository
`--force`	Replaces a `koboyo` skill folder or server entry that koboyo did not write
`--print`	Prints a section to paste into `AGENTS.md`, for agents that do not load skills

Run it again after upgrading koboyo to update the skill. Restart the agent, or reload its MCP servers, to pick up the changes.

Set it up by hand#

Every snippet below starts the server with npx, so it always runs the published package.

Claude Code

claude mcp add koboyo -- npx -y koboyo mcp

Add --scope user to have it in every project, or --scope project to share it with your team through .mcp.json.

Codex

codex mcp add koboyo -- npx -y koboyo mcp

Or add it to ~/.codex/config.toml:

[mcp_servers.koboyo]
command = "npx"
args = ["-y", "koboyo", "mcp"]

Cursor. Add this to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "koboyo": {
      "command": "npx",
      "args": ["-y", "koboyo", "mcp", "--root", "${workspaceFolder}"]
    }
  }
}

VS Code. Add this to .vscode/mcp.json in your project:

{
  "servers": {
    "koboyo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "koboyo", "mcp", "--root", "${workspaceFolder}"]
    }
  }
}

Windsurf. Add this to ~/.codeium/windsurf/mcp_config.json, with the path to your project:

{
  "mcpServers": {
    "koboyo": {
      "command": "npx",
      "args": ["-y", "koboyo", "mcp", "--root", "/path/to/your/project"]
    }
  }
}

On Windows, if your agent cannot start npx, use "command": "cmd" and put "/c", "npx" at the start of args.

Which files it can touch#

The server reads diagram files from, and writes images into, one folder: the folder it was started in, or the one --root names. It refuses any path outside that folder, including through a symlink. If it was started in your home folder or at the root of the disk without --root, it writes nothing and asks your agent to tell you to add --root. Drawing a preview from code still works in the meantime.

The tools#

tool	what it does
`get_syntax`	The cheatsheet and style guide for one diagram kind
`preview_diagram`	Draws code and returns the picture, without writing anything
`render_diagram`	Writes an SVG, PNG or HTML file into your project and returns the picture
`check_diagram`	Lists errors and warnings by line, without drawing
`find_icon`	Exact icon refs (`tech:redis`, `aws:lambda`) for many things at once

Four more tools let your agent hand a diagram to you in the editor, read your changes and comments back, and answer your comments. See edit diagrams locally.

tool	what it does
`open_editor`	Opens a diagram in the Koboyo editor in your browser, with an optional message
`wait_for_edits`	Waits for you to send it back, then returns what changed, your comments and a picture
`read_drawing`	Reads a board as it is now (its boxes, arrows, labels and comments) with a picture
`reply_to_comment`	Replies under one of your comments, marks it resolved, or both

The server also lists a few tools of the hosted server, such as create_diagram, which saves a diagram to a Koboyo board with live embed links. Those need Koboyo Pro. Called locally, they answer with how to set that up.

Ask for a diagram#

Once it is set up, ask in plain words: "draw the architecture of this repo", "add a sequence diagram of the checkout request to the README", "turn this Mermaid chart into a Koboyo diagram". For a codebase, the agent reads the package manifests, entry points, schema and deploy config first, and names every box after a real module, so the diagram matches the code.

Loading…