@circuitry-ide/mcp-server

MCP (Model Context Protocol) server that gives AI coding agents access to Circuitry - a visual workflow and diagramming platform.

What It Does

• Visualize Code: Create code nodes from project files with bidirectional sync

• Understand Diagrams: AI agents can comprehend user-drawn flowcharts and diagrams

• Create Flowcharts: Generate visual flowcharts via Circuitry's chat agent

• Data Visualization: Create spreadsheets and charts from code analysis

Prerequisites

1. Circuitry Server - Download from circuitry.dev/download

2. Node.js 18+

3. An MCP-compatible AI client (Claude Code, Cursor, VS Code, Gemini CLI, etc.)

Setup

1. Install & Configure Circuitry Server

1. Download Circuitry Server from circuitry.dev/download

2. Launch the app (appears in your system tray)

3. Click the tray icon → Server → Preferences

4. Click "Generate New Access Key"

5. Copy the key — you'll need it in the next step

2. Run MCP Setup (Required)

npx @circuitry-ide/mcp-server setup

This will prompt you to enter:

• EServer address — press Enter for default (http://localhost:3030)

• Access key — paste the key you generated above

This stores your credentials in ~/.circuitry/mcp-config.json.

3. Add to Your AI Client

Claude Code

claude mcp add circuitry npx @circuitry-ide/mcp-server

Or manually add to ~/.claude/config.json:

{
  "mcpServers": {
    "circuitry": {
      "command": "npx",
      "args": ["-y", "@circuitry-ide/mcp-server"]
    }
  }
}

Cursor

Settings → MCP → Add New MCP Server:

{
  "mcpServers": {
    "circuitry": {
      "command": "npx",
      "args": ["-y", "@circuitry-ide/mcp-server"]
    }
  }
}

VS Code / Copilot

code --add-mcp '{"name":"circuitry","command":"npx","args":["-y","@circuitry-ide/mcp-server"]}'

Gemini CLI

gemini mcp add circuitry npx @circuitry-ide/mcp-server

Cline / Windsurf

Add to your MCP configuration using the standard format above.

4. Restart Your Client

Restart your AI client to load the MCP server.

Usage Examples

Visualize Code Files

You: Show me the auth files as code nodes in Circuitry

Agent: I'll create code nodes from your auth files...
Done! Created 4 code nodes:
- auth/login.ts
- auth/logout.ts
- auth/middleware.ts
- auth/types.ts

Changes sync bidirectionally with your source files.

Understand User-Drawn Flows

You: I've drawn a flow of how I think the auth should work

Agent: I'll analyze your flow in Circuitry...

I can see you've drawn a 5-node authentication flow:
1. Start → Login Form
2. Login Form → Validate Credentials
3. Validate Credentials → branches to Success/Failure
...

Create Flowcharts

You: Create a flowchart showing the error handling flow

Agent: I'll ask Circuitry's agent to create this flowchart...

Done! Created a flowchart with 7 nodes showing:
- Error detection
- Classification (runtime vs validation)
- Logging paths
- User notification
- Recovery options

Available Tools

Connection

Workflow Understanding

Node Operations

Code Nodes

Sheet Nodes

The tables above are a hand-picked highlight. The full tool catalog is fetched live from the connected Circuitry app (see below), so it grows with the app — there may be many more tools available than are listed here.

How tools stay in sync (dynamic discovery)

This package does not hard-code the tool catalog. On a successful circuitry.connect, the server fetches the app's live tool definitions over the existing relay (tools.getDefinitions) and advertises them to your AI client — so when Circuitry adds a tool, you get it without updating this package.

Resolution order for the active tool list:

1. Live fetch from the connected app (freshest).

2. Disk cache of the last successful fetch (~/.circuitry-mcp/tools-cache.json) — used when offline.

3. Bundled snapshot (tools-snapshot.json, shipped in the npm tarball) — first-run fallback.

The circuitry.* connection tools are always available regardless of source.

If the app reports it needs a newer server than you have (version handshake), the server keeps working with whatever it can parse and surfaces an update-required notice on circuitry.connect / circuitry.status:

npm i -g @circuitry-ide/mcp-server@latest   # or just use `npx @circuitry-ide/mcp-server`

The bundled snapshot is regenerated at publish time from the app's source of truth (circuitry/src/lib/circuitry-api/tool-definitions.ts) via npm run mcp:generate in the app repo. There is no manual parity step to run.

Dynamic discovery landed in 2.1.0 — see CHANGELOG.md.

Safety note — external write tools

Tools invoked through this MCP server run against the app without the chat's plan-approval UI that gates the in-app agent. The mitigations are: (1) the connection itself is user-approved via the permission dialog raised by circuitry.connect, and (2) most edits are revertible via workflow.undo.

Configuration

Config File

Location: ~/.circuitry/mcp-config.json

{
  "eserverUrl": "http://localhost:3030",
  "accessKey": "your-key-here",
  "configured": true
}

Environment Variables

Commands

# Run setup wizard
npx @circuitry-ide/mcp-server setup

# Check current configuration
npx @circuitry-ide/mcp-server status

Troubleshooting

"Cannot connect to EServer"

1. Check EServer is running: Look for the Circuitry icon in your system tray

2. Start Circuitry Server: Download from circuitry.dev/download

3. Verify URL: Run npx @circuitry-ide/mcp-server status

"Invalid access key"

1. Create new key: Circuitry Server → Preferences → Generate New Access Key

2. Re-run setup: npx @circuitry-ide/mcp-server setup

"No Circuitry browser client connected"

1. Open Circuitry: Make sure the Circuitry app is open

2. Refresh: Try refreshing the Circuitry page

Development

# Clone and install
git clone https://github.com/circuitry-dev/circuitry-mcp-server.git
cd circuitry-mcp-server
npm install

# Build
npm run build

# Test locally
npx tsx src/index.ts setup
npx tsx src/index.ts status

To test local changes, point your MCP config to the built output:

{
  "mcpServers": {
    "circuitry": {
      "command": "node",
      "args": ["/path/to/circuitry-mcp-server/dist/index.js"]
    }
  }
}

License

This is proprietary software, provided so you can install and run it to connect your AI tools to the Circuitry service. The source is published for transparency and interoperability — it is not open-source, and viewing it grants no right to copy, modify, redistribute, or build a competing product. You may download, install and run it to use Circuitry; all other rights are reserved. See LICENSE for the full terms. "Circuitry" and the Circuitry logo are trade marks of Circuitry.

Use of the Circuitry service through this software is also governed by the Circuitry Terms of Service.

Links

• Circuitry Website

• Download Circuitry Server

• Report Issues