# digikey-mcp

`digikey-mcp` is a read-only DigiKey Product Information V4 sourcing assistant for electronics
engineers. It provides candidate search, authoritative part details, requirements-led BOM
planning, refinement, validation, comparison, and fail-closed order-list export through a CLI and
a genuine MCP stdio server.

> **For AI agents:** Read [`AGENT.md`](AGENT.md) before installing, importing, configuring, or
> using this repository. It explains the MCP server, the companion skill, supported workflows,
> safety rules, and verification steps.

It does not place orders, change DigiKey accounts, check out, scrape the DigiKey website, or
invent part numbers, prices, stock, specifications, URLs, or compatibility claims. Human review
is required for critical electrical, thermal, EMC, and safety decisions.

## Install

Python 3.11+ is required. `uv` is recommended for the reproducible clone-and-run workflow:

```bash
uv sync --all-groups
uv run python -m digikey_bom --help
```

The project exposes `digikey-bom` and `digikey-mcp` console scripts after installation.

`uv` is not required at runtime. To use the standard Python tooling instead:

```bash
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell: .venv\\Scripts\\Activate.ps1
python -m pip install --upgrade pip
python -m pip install .
digikey-mcp --help
```

For a published package, run `python -m pip install digikey-mcp` once the package is available
from your chosen package index. Offline mode works without DigiKey credentials or network access.

## Configuration and modes

Copy `.env.example` to `.env` only for local configuration. Supported modes are:

- `offline` (default): synthetic, visibly fixture-labeled data; no credentials or network.
- `sandbox`: DigiKey sandbox Product Information V4 API.
- `production`: DigiKey production Product Information V4 API.

Sandbox and production require a DigiKey developer subscription/application and the process
environment variables `DIGIKEY_CLIENT_ID`, `DIGIKEY_CLIENT_SECRET`, and `DIGIKEY_ACCOUNT_ID` for
ProductDetails calls. OAuth uses the two-legged `client_credentials` flow; tokens are cached in
memory only and never written to artifacts or logs. The client uses only official V4 keyword-search
and ProductDetails endpoints.

Keyword results are discovery evidence and may be stale. Current price and availability for a
purchase-ready line come from ProductDetails. Rate limits and transient failures use bounded,
injectable retries.

## CLI

Offline examples work without credentials:

```bash
python -m digikey_bom search "24V to 5V 5A buck converter" --mode offline
python -m digikey_bom details DEMO-10K-0603-ND --mode offline
python -m digikey_bom bom "Build a Raspberry Pi 5 robot power and I/O BOM" --build-quantity 2 --format markdown --output-dir output
python -m digikey_bom validate-bom output/bom.json --mode offline
python -m digikey_bom export-bom output/bom.json --format tsv --mode offline
python -m digikey_bom refine-bom output/bom.json "must use 0603 package" --mode offline
python -m digikey_bom compare DEMO-10K-0603-ND DEMO-10K-REEL-ND --mode offline
digikey-mcp serve
```

Use `--json` on search, details, BOM, refine, validate, and compare for complete structured data.
`export-bom` emits the selected format to stdout. The default export excludes `POSSIBLE_MATCH` and
`NO_VERIFIED_PART_FOUND`; `--include-possible-matches` is explicitly unsafe review output.

## MCP

The server exposes exactly these tools over stdio:

`digikey_search_parts`, `digikey_get_part_details`, `digikey_build_electronics_bom`,
`digikey_refine_bom`, `digikey_validate_bom`, `digikey_export_order_list`, and
`digikey_compare_candidates`.

Example Claude Desktop/Claude Code-style configuration:

```json
{
  "mcpServers": {
    "digikey": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/digikey-mcp", "digikey-mcp", "serve"],
      "env": {"DIGIKEY_MODE": "offline"}
    }
  }
}
```

For live use, set DigiKey variables in the client environment. Do not paste secrets into prompts
or skill instructions.

## Evidence and artifacts

Every BOM line has one status:

- `VERIFIED_MATCH`: exact DKPN observed in ProductDetails and every critical requirement verified.
- `VERIFIED_WITH_ASSUMPTION`: exact DKPN observed; remaining engineering assumptions are explicit.
- `POSSIBLE_MATCH`: exact DKPN observed, but a critical fact is missing, stale, or ambiguous.
- `NO_VERIFIED_PART_FOUND`: no safe part selected; failure and next action are retained.

The canonical artifact is schema `1.0.0`, saved as `output/bom.json` by default. Optional views
include requested/purchase quantity, DKPN, MPN, package/MOQ, stock, price, lifecycle, datasheet,
product URL, and selection notes. Custom, user-provided, and non-DigiKey items remain separate.

The portable Claude-compatible skill is [`skills/digikey-bom/SKILL.md`](skills/digikey-bom/SKILL.md),
with workflow references and examples for robot power, CAN, sensor boards, multi-board BOMs, and
substitutions.

Agent handoff instructions are in [`AGENT.md`](AGENT.md).

## Testing and development

Default tests are offline and use synthetic or mocked official-API-shaped responses. No real
credentials or network calls are required:

```bash
uv run ruff format --check .
uv run ruff check src tests
uv run mypy src
uv run pytest -q
uv build
uv run twine check dist/*
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`SECURITY.md`](SECURITY.md).

## Limitations

DigiKey price, stock, lifecycle, and availability data change. A returned part is not a complete
electrical design, certification, thermal proof, safety case, EMC result, or schematic/layout
review. Re-check ProductDetails before purchasing and obtain qualified human review for power,
fault, battery, motor, E-stop, and other safety-critical decisions.

## License

Copyright 2026 digikey-mcp contributors. Licensed under Apache-2.0; see [LICENSE](LICENSE).