MCP Server

This feature was added recently and might still change in future versions.

Part-DB ships a Model Context Protocol (MCP) server, which allows AI assistants and agents (like Claude, ChatGPT, or AI-powered coding tools) to directly interact with your Part-DB inventory: they can search for parts, look up categories, footprints, manufacturers, storage locations, suppliers, and projects, and even query external info providers like Digikey, Mouser or LCSC, all using natural language, without you having to write any code against the REST API.

MCP is a standardized, widely supported protocol, so once your Part-DB MCP endpoint is set up, you can connect it to many different AI clients and applications.

The MCP integration is currently read-only: an AI assistant can look up data, but it can not create, change or delete anything in your Part-DB instance via MCP. Still, giving an AI assistant access to your inventory means it can read everything the connected user account is allowed to see, so only connect trusted AI clients and keep your API token secret, just like you would for the REST API.

Enabling the MCP server

The MCP server is disabled by default and has to be enabled by an administrator first:

  1. Open the system settings and go to the AI tab.
  2. In the MCP (Model Context Protocol) Server section, enable the Enable MCP endpoint checkbox.

This can also be controlled via the MCP_ENABLED environment variable.

Once enabled, the MCP server is reachable under the /mcp path of your Part-DB instance (e.g. https://your-part-db.local/mcp). Unlike most other Part-DB pages, this path is not locale-prefixed (so it is /mcp, not /en/mcp).

Permissions

Users which should be allowed to use the MCP tools additionally need the Use MCP tools (for AI agents) permission (under the API permission group). Granting it automatically also grants the base Access API permission.

Like the REST API, authentication against the MCP endpoint is done using an API token. A token with the Read-Only scope is enough to use all currently available MCP tools, as they only read data.

Connecting an AI client

To connect an AI client to Part-DB, you need two things:

  • The MCP endpoint URL, e.g. https://your-part-db.local/mcp. Once you have the required permission, you can also find it on the API panel of your user settings page, under “MCP endpoint”, together with a copy-to-clipboard button.
  • An API token. Create one on the same API panel of your user settings page (see Authentication for details about tokens and scopes). A token with the Read-Only scope is sufficient.

The client has to send this token as a bearer token in the Authorization header of every request: Authorization: Bearer tcp_<your-token>. How exactly you configure this depends on the AI client you use; some examples for common clients are shown below.

Part-DB’s MCP server only supports the Streamable HTTP transport (no stdio, no plain SSE). Most modern MCP clients support this transport directly. Clients that only support local, stdio-based MCP servers can be bridged to a remote HTTP server with a small proxy tool like mcp-remote, as shown in the Claude Desktop example below.

MCP client configuration formats change frequently, so if the examples below don’t quite match what you see in your client, check the client’s own documentation for how to add a remote MCP server with a custom Authorization header.

Claude Code

Add the server with the Claude Code CLI:

claude mcp add part-db https://your-part-db.local/mcp \
  --transport http \
  --header "Authorization: Bearer tcp_<your-token>"

Claude Desktop

Claude Desktop currently only launches local (stdio) MCP servers directly from its config file, so a remote server like Part-DB’s has to be bridged with the mcp-remote proxy. Open Claude Desktop’s configuration file (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "part-db": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-part-db.local/mcp",
        "--header",
        "Authorization: Bearer tcp_<your-token>"
      ]
    }
  }
}

Google Antigravity

Open Manage MCP Servers and add the server via its JSON configuration:

{
  "mcpServers": {
    "part-db": {
      "serverUrl": "https://your-part-db.local/mcp",
      "headers": {
        "Authorization": "Bearer tcp_<your-token>"
      }
    }
  }
}

Cursor

Add the following to your .cursor/mcp.json (project-specific) or global Cursor MCP settings:

{
  "mcpServers": {
    "part-db": {
      "url": "https://your-part-db.local/mcp",
      "headers": {
        "Authorization": "Bearer tcp_<your-token>"
      }
    }
  }
}

VS Code (MCP support / GitHub Copilot)

Add the following to your .vscode/mcp.json (or use the MCP: Add Server command from the command palette):

{
  "servers": {
    "part-db": {
      "type": "http",
      "url": "https://your-part-db.local/mcp",
      "headers": {
        "Authorization": "Bearer tcp_<your-token>"
      }
    }
  }
}

Other clients

Any MCP client that supports the Streamable HTTP transport with custom headers can connect to Part-DB, you generally just need to provide:

  • URL: https://your-part-db.local/mcp
  • Transport: Streamable HTTP
  • Header: Authorization: Bearer tcp_<your-token>

Available tools

The following MCP tools are currently available. All of them are read-only.

Parts

  • search_parts – Search for parts by a keyword, with toggles to control which fields are searched (name, description, comment, tags, storage location, supplier order number, MPN, IPN, supplier, manufacturer, footprint, category, database ID), and an optional regex mode.
  • get_part_details – Get full details about a specific part by its database ID, including stock, prices, order details, attachments, parameters and EDA info.

Master data

Categories, footprints, manufacturers, storage locations, measurement units, suppliers and part custom states all expose the same pair of tools:

  • list_categories / get_category_details
  • list_footprints / get_footprint_details
  • list_manufacturers / get_manufacturer_details
  • list_storage_locations / get_storage_location_details
  • list_measurement_units / get_measurement_unit_details
  • list_suppliers / get_supplier_details
  • list_part_custom_states / get_part_custom_state_details

Each list_* tool accepts an optional keyword, matched against the name and comment. Without a keyword, all elements are returned in hierarchical tree order; with a keyword, matching results are sorted by their full path, so parent/child relationships can still be derived from the flat list. Each get_*_details tool takes the element’s database id and returns its full details.

Projects

  • list_projects / get_project_details – Same behavior as the master data tools above. get_project_details additionally returns the project’s BOM entries, status, description and associated build part.

Info Provider System

These tools query external part information providers (e.g. Digikey, Mouser, LCSC), see the Information provider system page for background:

  • list_info_providers – List the info providers that are currently active and can be used with the two tools below.
  • search_info_providers – Search one or more external info providers (or the configured default providers, if none are specified) for parts matching a keyword.
  • get_info_provider_part_details – Get full details (datasheets, images, parameters, prices, …) for a specific search result, identified by the provider_key and provider_id returned by search_info_providers.