Repository avatar
Other Tools
v0.3.0
active

arkanva

io.github.akarkode/arkanva

Create, edit, import and export Arkanva architecture diagrams and flowcharts.

Documentation

Arkanva MCP server

npm node license MCP

The official Model Context Protocol server for Arkanva, the hand-drawn 3D pastel diagramming workspace. It lets Claude Code, Claude Desktop, Cursor, Windsurf, Codex and any other MCP client create, read, edit, import, export and share Arkanva architecture diagrams, flowcharts and system designs in your workspace.

  • 20 tools: diagrams, folders, edits with auto-layout, symbol search across AWS, Azure, Google Cloud, Alibaba Cloud and generic catalogues, templates, Mermaid / draw.io / Excalidraw import, SVG / PNG / GIF / Mermaid / draw.io export, sensitive-data masking and share links.
  • Atomic edits: every batch of up to 200 operations applies completely or not at all, checked against the diagram revision.
  • Human in the loop: deletions, large edits and public sharing come back as confirmation_required and only apply after you approve them.
  • A single self-contained file with no runtime dependencies. It talks to Arkanva over HTTPS with your agent token and writes nothing but MCP frames to stdout.

Requirements

  • Node.js 20 or newer.
  • An Arkanva account on a plan that includes agent access.
  • An agent token (akf_…): open arkanva.com/app, then Account → Agent access → Create token. The token is shown once; copy it.

Install

You do not install anything by hand: your MCP client runs npx -y @arkanva/mcp, which downloads and starts the latest release. To pin it globally instead, run npm install -g @arkanva/mcp and use arkanva-mcp as the command.

Claude Code

claude mcp add -s user arkanva --env ARKANVA_API_KEY=akf_your_token -- npx -y @arkanva/mcp

-s user makes the server available in every project. Check it with claude mcp list.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart the app:

{
  "mcpServers": {
    "arkanva": {
      "command": "npx",
      "args": ["-y", "@arkanva/mcp"],
      "env": { "ARKANVA_API_KEY": "akf_your_token" }
    }
  }
}

If Claude Desktop on Windows cannot start npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "@arkanva/mcp"].

Cursor

Add the same mcpServers block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project; keep the token out of version control).

Windsurf

Add the same mcpServers block to ~/.codeium/windsurf/mcp_config.json, then refresh the MCP servers in Windsurf settings.

VS Code

.vscode/mcp.json:

{
  "servers": {
    "arkanva": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@arkanva/mcp"],
      "env": { "ARKANVA_API_KEY": "akf_your_token" }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.arkanva]
command = "npx"
args = ["-y", "@arkanva/mcp"]
env = { ARKANVA_API_KEY = "akf_your_token" }

Configuration

VariableRequiredDefaultPurpose
ARKANVA_API_KEYyesAgent token (akf_…). ARKANVA_TOKEN is accepted as an alias.
ARKANVA_API_URLnohttps://arkanva.comArkanva address, for self-hosted servers. Must be https, except localhost.
ARKANVA_CHROME_PATHnoauto-detectedChrome, Chromium or Edge used to render PNG and GIF exports.
npx -y @arkanva/mcp --help
npx -y @arkanva/mcp --version

The token sits in your client configuration in plain text. Keep that file private, never commit it, and revoke the token under Account → Agent access if it leaks. Tokens expire; when one does, tools answer with a 401 error that tells you to create a new one.

Tools

ToolWhat it doesAccess
arkanva_describeAPI version, token scopes, plan features and limitsread-only
arkanva_list_documentsList diagrams, optionally in one folderread-only
arkanva_open_documentFull diagram content and revisionread-only
arkanva_get_elementOne node or edgeread-only
arkanva_create_documentCreate an empty diagramadditive
arkanva_update_documentRename a diagram or move it between foldersadditive
arkanva_apply_operationsAdd, update, remove and reorder nodes and edges, with optional layoutdestructive
arkanva_delete_documentDelete a diagram (asks for confirmation)destructive
arkanva_search_symbolsSearch cloud, infrastructure, UML, flowchart and other symbolsread-only
arkanva_list_style_tokensPastel colour and style tokens for nodes and edgesread-only
arkanva_list_foldersList foldersread-only
arkanva_create_folderCreate a folderadditive
arkanva_update_folderRename a folderadditive
arkanva_delete_folderDelete a folder, keeping or deleting its diagrams (asks first)destructive
arkanva_import_documentNew diagram from Mermaid, draw.io, Excalidraw or .arkanva.jsonadditive
arkanva_export_documentSVG, PNG, animated GIF, Mermaid, draw.io or .arkanva.jsonadditive
arkanva_list_templatesOfficial templatesread-only
arkanva_create_from_templateNew diagram from a templateadditive
arkanva_sanitize_documentFind and mask IPs, hosts, emails, keys and ARNsdestructive
arkanva_manage_sharePublic read-only link status, enable (asks first), disable, refreshadditive

Every input is validated against its JSON schema before any request is sent. Full parameter reference: arkanva.com/docs.

Example prompts

  • "Draw the architecture of a serverless checkout on AWS in Arkanva: API Gateway, Lambda, DynamoDB and SQS, laid out left to right."
  • "Open my Payments diagram and add a Redis cache between the API and Postgres."
  • "Import this Mermaid flowchart into Arkanva in the Onboarding folder."
  • "Export the Platform overview diagram as a PNG at 2x to ./platform.png."
  • "Check the Network diagram for IP addresses and secrets and show me what would be masked."

Errors

Failures come back as MCP tool errors (isError: true) with the HTTP status, an error code and a hint. The common ones:

CodeMeaning
unauthorized (401)Token wrong, expired or revoked: create a new one
insufficient_scopeToken lacks the scope, e.g. documents:delete
plan_requiredThe feature is not in the account plan
quota_exceededPlan limit reached; the error includes limit and current
rate_limited (429)Too many calls; wait a minute
revision_conflictThe diagram changed; open it again and rebuild the batch
confirmation_requiredAsk the user, then repeat the call with the returned confirmation

Startup problems (missing token, bad URL) are printed to stderr and the process exits with code 1, which MCP clients show in their server log.

License

MIT for this package. The bundled open-source packages and the Nunito font keep their own licenses, listed in dist/third-party-notices.txt.

NPM
@arkanva/mcp
Install Command
npm install @arkanva/mcp
Runtime: npx