@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

Circuitry Server - Download from circuitry.dev/download
Node.js 18+
An MCP-compatible AI client (Claude Code, Cursor, VS Code, Gemini CLI, etc.)

Setup

1. Install & Configure Circuitry Server

Download Circuitry Server from circuitry.dev/download
Launch the app (appears in your system tray)
Click the tray icon → Server → Preferences
Click "Generate New Access Key"
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"

Check EServer is running: Look for the Circuitry icon in your system tray
Start Circuitry Server: Download from circuitry.dev/download
Verify URL: Run npx @circuitry/mcp-server status

"Invalid access key"

Create new key: Circuitry Server → Preferences → Generate New Access Key
Re-run setup: npx @circuitry/mcp-server setup

"No Circuitry browser client connected"

Open Circuitry: Make sure the Circuitry app is open
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

Circuitry MCP Server