# mouser-search-mcp

Model Context Protocol server for the [Mouser Electronics Search API](https://api.mouser.com/api/docs/ui/index).

Exposes the Mouser Search API as MCP tools so MCP-aware clients (Claude Code, Claude Desktop, etc.) can query Mouser's parts catalog.

## Tools

| Tool | Endpoint | What it does |
| --- | --- | --- |
| `search_by_keyword` | `POST /api/v1/search/keyword` | Keyword search across the catalog (up to 50 parts). Supports paging and RoHS/in-stock filters. |
| `search_by_part_number` | `POST /api/v1/search/partnumber` | Look up 1–10 part numbers (pipe-separated), with optional exact-match. |
| `search_by_keyword_and_manufacturer` | `POST /api/v2/search/keywordandmanufacturer` | Keyword search scoped to one manufacturer by name. |
| `search_by_part_number_and_manufacturer` | `POST /api/v2/search/partnumberandmanufacturer` | Part-number lookup scoped to one manufacturer by name. |
| `list_manufacturers` | `GET /api/v2/search/manufacturerlist` | Enumerate manufacturer names (use the result to populate the `manufacturer_name` argument on the two manufacturer-filtered tools). |

## Prerequisites

- Python 3.10+
- A Mouser **Search API** key — request one at <https://www.mouser.com/api-search/>.

## Install

Using [`uv`](https://docs.astral.sh/uv/) (recommended):

```bash
uv pip install -e .
```

Or with pip:

```bash
pip install -e .
```

## Configure

The server reads the API key from the `MOUSER_API_KEY` environment variable. Copy `.env.example` to `.env` and fill in your key, or export it in your shell.

## Run

The server speaks MCP over stdio:

```bash
MOUSER_API_KEY=... mouser-search-mcp
```

## Use with Claude Code

Register the server (replace the path and key):

```bash
claude mcp add mouser-search \
  --env MOUSER_API_KEY=your-key \
  -- mouser-search-mcp
```

## Use with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mouser-search": {
      "command": "mouser-search-mcp",
      "env": {
        "MOUSER_API_KEY": "your-key"
      }
    }
  }
}
```

If `mouser-search-mcp` is not on your `PATH`, point `command` at the absolute path to the script (e.g. inside your venv's `bin/`).

## Notes

- Mouser returns at most 50 records per search response. Use `records` + `starting_record` (v1 keyword search) or `records` + `page_number` (v2 keyword+manufacturer search) to page.
- `search_options` accepts `None`, `Rohs`, `InStock`, or `RohsAndInStock` — only one at a time.
- `part_search_options` accepts `None` or `Exact`.
- The cart and order endpoints documented by Mouser require an Ordering API key and are **not** exposed by this server — it covers search only.

## Releasing

Versioning and releases are fully automated by [`python-semantic-release`](https://python-semantic-release.readthedocs.io/). Every push to `main` runs `.github/workflows/release.yml`, which:

1. Inspects commits since the last tag.
2. Decides the next version (or does nothing if no release-worthy commits).
3. Updates `version` in `pyproject.toml`, generates the changelog, commits, and pushes a `vX.Y.Z` tag.
4. Builds wheel + sdist and uploads them to PyPI.
5. Creates a GitHub Release with auto-generated notes.

### Commit grammar

Commits must follow [Conventional Commits](https://www.conventionalcommits.org/). The leading keyword decides the bump:

| Prefix | Bump | Example |
| --- | --- | --- |
| `feat:` | minor | `feat: add list_manufacturers tool` |
| `fix:` | patch | `fix: handle empty Errors array` |
| `perf:` | patch | `perf: reuse httpx client` |
| `feat!:` / `BREAKING CHANGE:` in body | major | `feat!: rename tools` |
| `docs:`, `chore:`, `refactor:`, `test:`, `ci:`, `style:` | none | (no release cut) |

Anything else is ignored. If you push a flurry of small commits, semantic-release collapses them into a single release on the next workflow run.

### One-time setup

These steps need to be done once in the GitHub UI before the workflow can publish:

1. **PyPI account + token** — create a PyPI account, then on the [API tokens page](https://pypi.org/manage/account/token/) generate an *account-scoped* token (the project doesn't exist on PyPI yet, so it can't be project-scoped on the first release; re-scope it to `mouser-search-mcp` after the first successful publish).
2. **Repo secret** — in GitHub: *Settings → Secrets and variables → Actions → New repository secret*, name `PYPI_API_TOKEN`, paste the token value.
3. **Workflow permissions** — *Settings → Actions → General → Workflow permissions* must be set to **Read and write permissions** so semantic-release can push the version bump commit and tag.

After that, just merge to `main` with a `feat:` or `fix:` commit and the rest happens automatically. To skip a release, use a non-bumping prefix (`docs:`, `chore:`, etc.) or include `[skip ci]` in the commit message.