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 () 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 withnpx, 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
| Tool | What it does | Plan |
|---|---|---|
create_diagram | A new diagram from boxes and links, laid out by itself (steps in one direction, few crossings) | Pro+ |
edit_diagram | Add, rename, reshape or delete boxes and links; new boxes go next to the one they follow | Pro+ |
tidy_diagram | Re-arrange a diagram, like Tidy up in Kelvo | Pro+ |
export_svg | Save a .kelvo board as a .kelvo.svg picture | Pro+ |
read_diagram | The boxes and links of a diagram, for the tool to work from | Every plan |
open_in_kelvo | Open a diagram in your browser, in Kelvo, as one of your boards | Every 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:
- the folder in
KELVO_ROOT, when you set it in the server's settings (as in the Claude Desktop example); - otherwise the folders your tool has open (VS Code, Claude Code and others tell Kelvo);
- 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 see | What to do |
|---|---|
| The tool says Kelvo isn't signed in | Run 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 found | Apps 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 up | Start 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 running | Use @kelvoapp/mcp@latest in the arguments, or clear npx's cache |
| Opening in Kelvo made several copies of a board | Each open adds a board. Delete the extras in All boards… |