tscircuit MCP Server
A Model Context Protocol (MCP) server that provides Claude with access to the tscircuit electronics component registry. This enables Claude to search, browse, and analyze electronic components and circuit packages from the tscircuit ecosystem.
Features
- Component Search: Search for electronic components by name, type, or description
- Package Details: Get comprehensive information about tscircuit packages
- Source Code Access: Retrieve component source code and implementation details
- Component Analysis: Analyze electrical specifications, footprints, and compatibility
- Caching: Built-in response caching for improved performance
- Error Handling: Robust error handling with meaningful error messages
Installation
Prerequisites
- Bun 1.0.0 or higher
- Alternatively, Node.js 18.0.0 or higher with npm
Setup
- Clone or download this repository
- Install dependencies:
bun install
- Build the project:
bun run build
- Test the server:
bun start
Development
For development with hot reload:
bun run dev
For type checking:
bun run typecheck
Usage with Claude Desktop
Configuration
Add the following to your Claude Desktop MCP configuration file:
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"tscircuit": {
"command": "bun",
"args": ["/path/to/tscircuit-mcp/build/index.js"]
}
}
}
Or if you prefer to use Node.js:
{
"mcpServers": {
"tscircuit": {
"command": "node",
"args": ["/path/to/tscircuit-mcp/build/index.js"]
}
}
}
Replace /path/to/tscircuit-mcp with the actual path to your installation.
Available Resources
The MCP server provides these resources that Claude can read:
Search Components
- URI:
tscircuit://packages/search?q={query}&limit={limit}&category={category} - Description: Search results from tscircuit registry
- Parameters:
q(required): Search querylimit(optional): Maximum results (default: 10)category(optional): Component category filter
Package Details
- URI:
tscircuit://packages/{packageName} - Description: Detailed package information
- Example:
tscircuit://packages/seveibar/red-led
Package Source Code
- URI:
tscircuit://packages/{packageName}/code?version={version} - Description: Component source code
- Parameters:
version(optional): Specific version (defaults to latest)
Available Tools
Claude can use these tools to interact with the tscircuit registry:
search_components
Search for electronic components in the tscircuit registry.
Parameters:
query(string, required): Search termslimit(number, optional): Maximum results (default: 10)category(string, optional): Component category filter
Example:
{
"query": "3.3V voltage regulator",
"limit": 5,
"category": "ic"
}
get_package_details
Get detailed information about a specific tscircuit package.
Parameters:
packageName(string, required): Full package name
Example:
{
"packageName": "seveibar/red-led"
}
get_package_code
Retrieve the source code for a tscircuit component.
Parameters:
packageName(string, required): Package nameversion(string, optional): Specific version
Example:
{
"packageName": "seveibar/red-led",
"version": "1.0.0"
}
analyze_component
Analyze a component's electrical specifications and footprint.
Parameters:
packageName(string, required): Package to analyze
Example:
{
"packageName": "seveibar/red-led"
}
Example Usage Scenarios
1. Component Search
Claude Query: "Find me a 3.3V voltage regulator in SOT-23 package"
Claude will use the search_components tool:
{
"query": "3.3V voltage regulator SOT-23",
"category": "ic"
}
2. Package Analysis
Claude Query: "What are the specifications of the ESP32 module package?"
Claude will use the get_package_details tool:
{
"packageName": "AnasSarkiz/ESP32_module"
}
3. Code Review
Claude Query: "Show me the implementation of the red LED component"
Claude will use the get_package_code tool:
{
"packageName": "seveibar/red-led"
}
4. Component Comparison
Claude Query: "Compare the specifications of these two resistor packages"
Claude will use multiple analyze_component calls to compare components.
API Reference
tscircuit Registry API
The server integrates with the official tscircuit registry at https://registry-api.tscircuit.com:
- Search:
POST /packages/searchwith body{"query": "search term"} - Package Info: Retrieved via search (no direct endpoint yet)
- Package Code: Accessed via npm package links
Package names follow the format author/package-name (e.g., seveibar/usb-c-flashlight) and are published to npm as @tsci/author.package-name.
Component Categories
Supported component categories for filtering:
resistor- Resistorscapacitor- Capacitorsinductor- Inductorsdiode- Diodestransistor- Transistorsic- Integrated circuitsconnector- Connectorsled- LEDsswitch- Switchessensor- Sensorscrystal- Crystals and oscillatorsrelay- Relaystransformer- Transformersfuse- Fusesbattery- Batteriesmotor- Motorsdisplay- Displaysantenna- Antennasother- Other components
Development
Scripts
bun run build- Build TypeScript to JavaScriptbun start- Start the MCP serverbun run dev- Development mode with hot reloadbun test- Run testsbun run typecheck- Type checking without compilation
Project Structure
tscircuit-mcp/
├── src/
│ ├── index.ts # Main entry point
│ ├── server.ts # MCP server implementation
│ ├── types.ts # TypeScript type definitions
│ └── tscircuit-api.ts # Registry API client
├── build/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
Error Handling
The server includes comprehensive error handling:
- Network timeouts and registry downtime
- Invalid package names (404 errors)
- Malformed requests
- API rate limiting
- Cache management
Performance Features
- Response Caching: 5-minute TTL for registry responses
- Request Timeouts: 10-second timeout for API calls
- Concurrent Requests: Efficient handling of multiple simultaneous requests
- Cache Statistics: Built-in cache monitoring
Troubleshooting
Common Issues
- Server won't start: Check Node.js version (requires 18.0.0+)
- Connection errors: Verify network connectivity to registry.tscircuit.com
- Package not found: Ensure package name is correct and exists in registry
- Slow responses: Check network connection and registry status
Debug Mode
Set the DEBUG environment variable to enable detailed logging:
DEBUG=tscircuit-mcp npm start
Cache Management
Clear the cache programmatically:
// Access through the server instance
server.getAPI().clearCache();
// Get cache statistics
const stats = server.getAPI().getCacheStats();
console.log(`Cache size: ${stats.size} entries`);
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
MIT License - see LICENSE file for details
Support
For issues and questions:
- Check the troubleshooting section above
- Review the tscircuit documentation
- Open an issue on the project repository