@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

Tool	Description
circuitry.status	Check connection status
circuitry.connect	Request connection (shows permission dialog)

Workflow Understanding

Tool	Description
workflow.getActive	Get current visible workflow info
workflow.getStructure	Get simplified workflow structure
workflow.resolveFlow	Resolve user reference ("this flow") to node IDs
workflow.getNodeSummary	Get simplified node details

Node Operations

Tool	Description
nodes.list	List all nodes in the workflow
nodes.get	Get a node by ID
nodes.update	Update node configuration
nodes.delete	Delete a node

Code Nodes

Tool	Description
code.create	Create code node (from file path with sync, OR with name+content)
code.createBatch	Create multiple code nodes from files
code.setCode	Update code content (syncs to source if applicable)

Sheet Nodes

Tool	Description
sheet.create	Create a spreadsheet node with data
sheet.setData	Replace sheet data

Agent Delegation

Tool	Description
agent.chat	Send message to Circuitry's chat agent
agent.createFlowchart	Ask agent to create a flowchart
agent.poll	Poll for agent response (async)

Configuration

Config File

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

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

Environment Variables

Variable	Description
CIRCUITRY_ESERVER_URL	Override EServer URL
CIRCUITRY_ACCESS_KEY	Override access key

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