Help

Kelvo in your AI coding tools

Your AI coding tool can draw diagrams of your code as Kelvo boards: flowcharts, architecture, request flows, sequences of steps, mind maps. Ask "draw how a request goes through this API as docs/request-flow.kelvo.svg" and a hand-drawn diagram appears in your project.

It works in any tool that speaks MCP (Model Context Protocol): Claude Code, Codex, GitHub Copilot, Cursor, OpenCode, Gemini CLI, Windsurf, Claude Desktop and others. The Kelvo MCP server is the npm package @kelvoapp/mcp.

What you get

  • A file in your project, such as docs/architecture.kelvo.svg. It's an ordinary picture: GitHub, GitLab, pull requests, READMEs (![Architecture](docs/architecture.kelvo.svg)) and editors show it.
  • A board inside that picture. Kelvo opens it as a board you can edit by hand: move boxes, restyle, add notes.
  • Changes later. Ask the tool to add a step, rename a box or tidy the layout; it reads the diagram and changes it.
  • Open in Kelvo. Ask "open it in Kelvo": the diagram opens in your browser as one of your boards (on Pro+ it also goes to your cloud, on all your devices). Each time you ask, it adds another board.

Nothing goes through Kelvo's servers: the tool reads and writes files on your computer, and the board travels to the browser inside the link. The only thing the server asks Kelvo is your plan, about once a day.

What you need

  • Kelvo Pro+ to make and change diagrams. Reading them and opening them in Kelvo work on every plan. See Accounts and plans.
  • Node.js 20 or later (node --version). The tools start the server with npx, which comes with Node.

1. Sign in on your computer

In a terminal:

npx @kelvoapp/mcp login

It opens your browser on Kelvo and shows a code (such as KDRW-7QXM). Check that the browser shows the same code, sign in if asked, and click Connect. The terminal then says Signed in as you@example.com · Pro+.

Do this once per computer. Every AI tool on that computer uses the same sign-in.

2. Add Kelvo to your tool

Pick your tool. Each one starts the server by itself when it needs it.

Claude Code

claude mcp add -s user kelvo -- npx -y @kelvoapp/mcp

-s user makes it available in all your projects; leave it out for this project only. Check it with /mcp in a new session.

Codex (CLI and IDE extension)

codex mcp add kelvo -- npx -y @kelvoapp/mcp

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

[mcp_servers.kelvo]
command = "npx"
args = ["-y", "@kelvoapp/mcp"]

The key is mcp_servers, with an underscore.

GitHub Copilot in VS Code

Add .vscode/mcp.json to your project (or the same in your user settings, for every project):

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

The top key is servers here, not mcpServers. Use Copilot Chat in Agent mode; Kelvo's tools appear under the tools button.

GitHub Copilot CLI

copilot mcp add kelvo -- npx -y @kelvoapp/mcp

Or type /mcp add inside Copilot CLI and choose a STDIO server with the command npx -y @kelvoapp/mcp.

Copilot's coding agent on github.com runs in the cloud, where your computer's sign-in isn't available: use Copilot in your editor or terminal instead.

Cursor

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

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

OpenCode

Add to opencode.json in your project, or your global OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kelvo": { "type": "local", "command": ["npx", "-y", "@kelvoapp/mcp"], "enabled": true }
  }
}

OpenCode wants the command as one list: program and arguments together.

Gemini CLI

Add to ~/.gemini/settings.json (or .gemini/settings.json in your project):

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Claude Desktop

Claude Desktop has no project folder, so tell Kelvo where to put diagrams with KELVO_ROOT. In Settings → Developer → Edit Config (claude_desktop_config.json):

{
  "mcpServers": {
    "kelvo": {
      "command": "npx",
      "args": ["-y", "@kelvoapp/mcp"],
      "env": { "KELVO_ROOT": "/Users/you/projects/my-app" }
    }
  }
}

Restart Claude Desktop afterwards.

Any other MCP tool

Kelvo is a local (stdio) MCP server. Give your tool the command npx with the arguments -y @kelvoapp/mcp.

3. Ask for a diagram

Try one of these:

  • Draw the architecture of this repo as docs/architecture.kelvo.svg
  • Draw the checkout flow in src/checkout as a top-to-bottom flowchart in docs/checkout.kelvo.svg, with decisions as diamonds
  • Read docs/architecture.kelvo.svg and add the cache between the API and the database, then tidy it
  • Open docs/architecture.kelvo.svg in Kelvo

Name a .kelvo.svg file to get a picture that also opens as a board (best for docs and READMEs), or .kelvo for a plain board file.

What the tools do

ToolWhat it doesPlan
create_diagramA new diagram from boxes and links, laid out by itself (steps in one direction, few crossings)Pro+
edit_diagramAdd, rename, reshape or delete boxes and links; new boxes go next to the one they followPro+
tidy_diagramRe-arrange a diagram, like Tidy up in KelvoPro+
export_svgSave a .kelvo board as a .kelvo.svg picturePro+
read_diagramThe boxes and links of a diagram, for the tool to work fromEvery plan
open_in_kelvoOpen a diagram in your browser, in Kelvo, as one of your boardsEvery plan

Which folder it works in

Kelvo only reads and writes diagram files (.kelvo.svg, .kelvo) inside your project, and never replaces a file that isn't a Kelvo board. The project is:

  1. the folder in KELVO_ROOT, when you set it in the server's settings (as in the Claude Desktop example);
  2. otherwise the folders your tool has open (VS Code, Claude Code and others tell Kelvo);
  3. otherwise the folder the tool started Kelvo in.

Your plan and staying signed in

The sign-in is a licence kept on your computer (in ~/.config/kelvo). Kelvo checks it without the internet; when you're online it's renewed about once a day, so a new plan counts straight away. Offline it keeps working for up to three weeks.

npx @kelvoapp/mcp whoami    # which account and plan this computer uses
npx @kelvoapp/mcp logout    # disconnect this computer

You can also disconnect a computer from Kelvo: Account & plan → Connected tools → Disconnect. That computer stops getting your plan the next time it checks in.

If something doesn't work

What you seeWhat to do
The tool says Kelvo isn't signed inRun npx @kelvoapp/mcp login in a terminal, then ask again
"Making and changing diagrams needs Kelvo Pro+"Upgrade in Account & plan; the tool sees the new plan within a few seconds
"Kelvo doesn't know which project folder to work in"Set KELVO_ROOT to your project folder in the server's settings (see Claude Desktop)
The tool can't start Kelvo, or says npx isn't foundApps opened from the Dock don't always see the Node you installed in a terminal (nvm, Homebrew). Put the full path instead of npx: run which npx and use what it prints
Kelvo's tools don't show upStart a new session or restart the tool after adding it; check the config file's top key (mcpServers, servers for VS Code, mcp for OpenCode, mcp_servers for Codex)
An old version keeps runningUse @kelvoapp/mcp@latest in the arguments, or clear npx's cache
Opening in Kelvo made several copies of a boardEach open adds a board. Delete the extras in All boards…