@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