nickweedon/partsbox_mcp

PartsBox MCP Server

A Model Context Protocol (MCP) server for the PartsBox API using FastMCP. This server enables AI assistants to interact with your PartsBox inventory management system for electronic components.

Overview

PartsBox is an inventory management system for electronic components. This MCP server provides tools to:

• Manage parts and their metadata
• Track stock levels and locations
• Handle lots and stock entries
• Manage storage locations
• Work with projects and BOMs (Bill of Materials)
• Process orders and receive stock

Requirements

• Python 3.10+
• uv package manager
• PartsBox API key (generated in Settings | Data)

Setup

1. Install dependencies

uv sync

2. Set up environment variables

Create a .env file in the project root:

PARTSBOX_API_KEY=partsboxapi_your_api_key_here

Security Note: Guard your API key carefully, as it provides full access to your PartsBox database.

Environment Variables

3. Run the server

uv run python partsbox_mcp_server.py

API Overview

The PartsBox API is operation-oriented (not REST) and provides:

Parts Management

• Create, retrieve, update, and delete parts
• Manage substitutes and meta-parts
• Handle custom fields

Stock Management

• Add and remove stock
• Move stock between locations
• Update stock entries
• Retrieve stock by part or storage location

Lots

• Get and update lot data
• Track lot information

Storage

• Manage storage locations
• Archive and restore locations
• Aggregate stock by location

Projects

• Create and manage BOMs
• Handle BOM entries
• Track project builds

Orders

• Create and manage orders
• Add order entries
• Receive stock from orders
• Manage order lifecycle

Available Tools

Parts API

Stock API

Lots API

Storage API

Projects API

Orders API

Files API

MCP Resources

Resources provide read-only access to files and images via URI templates:

The file_id is obtained from part data (e.g., the part/img-id field returned by get_part or list_parts).

Shared Resource Storage

The server provides resource-based file storage methods (get_image_resource and get_file_resource) that enable sharing files with other MCP servers through a mapped Docker volume. This is useful for multi-container workflows where files need to be passed between services.

How It Works

1. Files are downloaded from PartsBox and stored in a shared blob storage directory
2. Each file gets a unique resource identifier (format: blob://TIMESTAMP-HASH.EXT)
3. Other MCP servers can access these files directly from the mapped volume using the identifier
4. Files are automatically deduplicated using SHA256 hashing
5. Files expire after a configurable TTL (default: 24 hours)

Configuration

Configure shared storage using environment variables:

Docker Volume Setup

To enable resource sharing between MCP servers, mount a shared volume:

# docker-compose.yml
version: '3.8'
services:
  partsbox-mcp:
    image: partsbox-mcp:latest
    volumes:
      - blob-storage:/mnt/blob-storage
    environment:
      - PARTSBOX_BLOB_STORAGE_ROOT=/mnt/blob-storage

  other-mcp-server:
    image: other-mcp:latest
    volumes:
      - blob-storage:/mnt/blob-storage

volumes:
  blob-storage:

Usage Example

# Store an image in shared storage
response = get_image_resource("img_resistor_10k")
# Returns: ResourceResponse(
#   success=True,
#   resource_id="blob://1733437200-a3f9d8c2b1e4f6a7.png",
#   filename="img_resistor_10k.png",
#   mime_type="image/png",
#   size_bytes=65536,
#   sha256="a3f9d8c2...",
#   expires_at="2024-12-08T12:00:00Z"
# )

# Other MCP servers can now access the file at:
# /mnt/blob-storage/17/33/blob://1733437200-a3f9d8c2b1e4f6a7.png

JMESPath Query Support

All list operations support JMESPath queries for filtering and projection. This server extends standard JMESPath with custom functions for safe null handling and data transformation:

Custom Functions

Null-Safe Queries

IMPORTANT: Many PartsBox fields are nullable. Use nvl() to prevent errors when filtering on these fields:

# UNSAFE - fails if "part/name" is null
query="[?contains(\"part/name\", 'resistor')]"

# SAFE - handles null values
query="[?contains(nvl(\"part/name\", ''), 'resistor')]"

Query Examples

# Search parts by name (null-safe)
query="[?contains(nvl(\"part/name\", ''), 'capacitor')]"

# Filter by manufacturer
query="[?nvl(\"part/manufacturer\", '') == 'Texas Instruments']"

# Combine conditions
query="[?contains(nvl(\"part/name\", ''), 'resistor') && \"stock/total\" > `0`]"

# Sort results
query="sort_by(@, &\"part/name\")"

Important Notes

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: APIKey partsboxapi_[your-key]

Timestamps

PartsBox stores timestamps as 64-bit UNIX UTC timestamps. Timezone conversion is your responsibility.

Stock Calculations

PartsBox does not store total stock counts. Stock counts are calculated by traversing stock history.

Rate Limiting

Rate limits may be enforced. Plan for potential rate limiting in your usage.

API Restrictions

• Cannot create user interface applications using the API (automation only)
• Commercial plan users receive standard support
• Free account users should not expect email responses

Claude Integration

This MCP server works with Claude Desktop and Claude Code (CLI). See for detailed configuration instructions.

Related Resources

• PartsBox API Documentation
• PartsBox Website

Developing

This project is designed to work with vscode and the devcontainers plugin. I recommend also running claude --dangerously-skip-permissions once inside the devcontainer for best results 😁