@circuitry/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/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/mcp-server

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

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

Cursor

Settings → MCP → Add New MCP Server:

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

VS Code / Copilot

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

Gemini CLI

gemini mcp add circuitry npx @circuitry/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

Agent Delegation

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/mcp-server setup

# Check current configuration
npx @circuitry/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/mcp-server status

"Invalid access key"

1. Create new key: Circuitry Server → Preferences → Generate New Access Key
2. Re-run setup: npx @circuitry/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

MIT

Links

• Circuitry Website
• Download Circuitry Server
• Report Issues