@circuitry/mcp-server

Name: Circuitry MCP Server
Author: circuitry-dev

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