circuit-mcp-server

jcmecham/circuit-mcp-server

3.2

If you are the rightful owner of circuit-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for reading and analyzing `.cddx` circuit diagram files, enabling interaction with Circuit Diagram Document files to extract component information, connections, and metadata.

Circuit Diagram MCP Server

A Model Context Protocol (MCP) server for reading and analyzing .cddx circuit diagram files. This server enables Claude Code to interact with Circuit Diagram Document files, extracting component information, connections, and metadata.

Features

  • Read Circuit Files: Parse .cddx files (ZIP archives containing XML circuit data)
  • Component Analysis: Extract component types, IDs, locations, and properties
  • Connection Mapping: Identify wires and connections between components
  • Metadata Extraction: Retrieve document metadata (author, dates, etc.)
  • Error Handling: Robust error handling for invalid files

What are .cddx Files?

.cddx files are Circuit Diagram Document files used by Circuit Diagram software. They are ZIP archives containing:

  • circuitdiagram/Document.xml - Main circuit diagram data in XML format
  • Additional metadata and resources

Installation

Prerequisites

  • Python 3.10 or higher
  • pip (Python package manager)
  • Internet connection (for downloading circuit-diagram CLI)

Step 1: Install MCP Server Dependencies

Open PowerShell or Command Prompt and navigate to this directory:

cd C:\Users\jcmec\Desktop\DevRepos\circuit-mcp-server

Install the required Python packages for the MCP server:

pip install -r requirements.txt

Step 2: Install Circuit Diagram CLI Tool

The MCP server uses the circuit-diagram CLI to render circuit diagrams. Install it automatically:

python setup.py

This will:

  • Download the circuit-diagram CLI binary for your platform (Windows/Linux/macOS)
  • Install it to the bin/ directory
  • Download circuit component files to the components/ directory
  • Verify the installation

Options:

  • python setup.py --force - Force reinstall even if already installed
  • python setup.py --path /custom/dir - Install to a custom directory

Note: On Linux, you may need to install libfontconfig1:

sudo apt-get install libfontconfig1

For detailed installation information, see README_INSTALL.md after running setup.

Step 3: Test the Server (Optional)

You can test the server standalone using the MCP inspector tool:

npx @modelcontextprotocol/inspector python circuit_server.py

This opens a web interface where you can test the read_circuit tool directly.

Configuration for Claude Code

Windows Configuration

Add the MCP server to your Claude Code configuration file:

Location: %APPDATA%\Claude\claude_desktop_config.json

(Typically: C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json)

Configuration to add:

{
  "mcpServers": {
    "circuit-diagram": {
      "command": "python",
      "args": [
        "C:\\Users\\jcmec\\Desktop\\DevRepos\\circuit-mcp-server\\circuit_server.py"
      ]
    }
  }
}

Important:

  • Use double backslashes (\\) in Windows paths
  • Replace C:\\Users\\jcmec\\ with your actual username/path if different
  • If you have other MCP servers, add this entry to the existing mcpServers object

Example Full Configuration

If this is your only MCP server:

{
  "mcpServers": {
    "circuit-diagram": {
      "command": "python",
      "args": [
        "C:\\Users\\jcmec\\Desktop\\DevRepos\\circuit-mcp-server\\circuit_server.py"
      ]
    }
  }
}

If you already have other servers:

{
  "mcpServers": {
    "existing-server": {
      "command": "existing-command",
      "args": ["..."]
    },
    "circuit-diagram": {
      "command": "python",
      "args": [
        "C:\\Users\\jcmec\\Desktop\\DevRepos\\circuit-mcp-server\\circuit_server.py"
      ]
    }
  }
}

Step 4: Restart Claude Code

After adding the configuration:

  1. Close Claude Code/Claude Desktop completely
  2. Reopen the application
  3. The circuit diagram server should now be available

Usage

Once configured, you can use Claude Code to analyze circuit files:

Example Commands

Read a circuit file:

Can you read the circuit diagram at C:\circuits\my_circuit.cddx?

Analyze components:

What components are in the circuit file C:\circuits\my_circuit.cddx?

Get connection information:

Show me the connections in C:\circuits\my_circuit.cddx

Using the read_circuit Tool

The MCP server provides the read_circuit tool that Claude can call automatically. The tool:

  • Input: Filepath to a .cddx file (absolute or relative path)
  • Output: Detailed analysis including:
    • Document metadata (author, creation date, etc.)
    • Number and types of components
    • Component properties and locations
    • Wire connections between components
    • Document attributes

Example Output

Circuit Diagram Analysis: example_circuit.cddx
============================================================

METADATA:
----------------------------------------
  Author: John Doe
  Created: 2024-01-15

COMPONENTS: 5
----------------------------------------
  [1] Type: Resistor, ID: R1
      Location: (100, 200)
      Resistance: 1kΩ
  [2] Type: Capacitor, ID: C1
      Location: (200, 200)
      Capacitance: 10µF
  [3] Type: LED, ID: D1
      Location: (300, 200)

COMPONENT SUMMARY BY TYPE:
----------------------------------------
  Resistor: 2 component(s)
  Capacitor: 1 component(s)
  LED: 2 component(s)

CONNECTIONS/WIRES: 4
----------------------------------------
  [1] Wire ID: wire_1
      From: (100, 200) To: (200, 200)
  [2] Wire ID: wire_2
      From: (200, 200) To: (300, 200)

Testing

Create a Test Circuit File

A sample .cddx file (test_circuit.cddx) is included in this repository for testing purposes.

Test with MCP Inspector

npx @modelcontextprotocol/inspector python circuit_server.py

Then use the web interface to call read_circuit with the test file path.

Test with Claude Code

  1. Ensure the server is configured in claude_desktop_config.json
  2. Restart Claude Code
  3. Ask Claude to analyze the test file:
Please analyze the circuit at C:\Users\jcmec\Desktop\DevRepos\circuit-mcp-server\test_circuit.cddx

Troubleshooting

Server Not Appearing in Claude Code

  1. Check that claude_desktop_config.json exists in %APPDATA%\Claude\
  2. Verify the JSON syntax is valid (use a JSON validator)
  3. Ensure paths use double backslashes (\\)
  4. Restart Claude Code completely

Python Not Found

If you get "python is not recognized":

  1. Ensure Python is installed and in your PATH
  2. Try using the full path to python.exe:
{
  "mcpServers": {
    "circuit-diagram": {
      "command": "C:\\Python311\\python.exe",
      "args": ["C:\\Users\\jcmec\\Desktop\\DevRepos\\circuit-mcp-server\\circuit_server.py"]
    }
  }
}

Module 'mcp' Not Found

Ensure you installed the requirements:

pip install -r requirements.txt

If using a virtual environment, ensure it's activated before installing.

Circuit Diagram CLI Not Found

If you get errors about circuit-diagram CLI not being found:

  1. Make sure you ran the installation script:
python setup.py
  1. Verify the CLI is installed:
./bin/circuit-diagram --help
# Windows: .\bin\circuit-diagram.exe --help
  1. If still not working, try reinstalling:
python setup.py --force

File Path Issues

  • Use absolute paths for .cddx files
  • Use Windows-style paths with backslashes or forward slashes
  • Ensure the file path exists and is accessible

Development

Project Structure

circuit-mcp-server/
├── circuit_server.py      # Main MCP server implementation
├── setup.py              # Installation script for circuit-diagram CLI
├── requirements.txt      # Python dependencies for MCP server
├── README.md            # This file
├── test_circuit.cddx    # Sample circuit file for testing
├── bin/                 # Created by setup.py - contains CLI executable
│   └── circuit-diagram  # (or circuit-diagram.exe on Windows)
├── components/          # Created by setup.py - circuit components
│   └── *.xml           # Component definition files
└── README_INSTALL.md   # Created by setup.py - CLI installation details

Extending the Server

To add more tools, edit circuit_server.py:

  1. Add a new tool in the list_tools() function
  2. Add handling in the call_tool() function
  3. Implement the tool logic

XML Schema

The Circuit Diagram XML typically follows this structure:

<CircuitDocument xmlns="http://schemas.circuit-diagram.org/circuitDiagramDocument/2012/document">
  <Metadata>
    <Properties>
      <Author>Name</Author>
      <Created>Date</Created>
    </Properties>
  </Metadata>
  <Elements>
    <Component Type="Resistor" id="R1">
      <Location x="100" y="200"/>
      <Properties>
        <Property name="Resistance" value="1kΩ"/>
      </Properties>
    </Component>
    <Wire id="wire_1">
      <Start x="100" y="200"/>
      <End x="200" y="200"/>
    </Wire>
  </Elements>
</CircuitDocument>

License

This project is provided as-is for educational and development purposes.

Support

For issues or questions:

  • Check the troubleshooting section above
  • Review MCP documentation: https://modelcontextprotocol.io
  • Ensure your .cddx files are valid Circuit Diagram documents