iFixit MCP Server

Full-coverage iFixit MCP server — repair guides, device info, repairability scores, categories, search, media, and contributor profiles in one server.

⚠️ LICENSE — READ FIRST

Two licenses apply — do not confuse them:

1. The code in this repository is licensed under the 0-Clause BSD License (0BSD) — free to use, copy, modify, and distribute for any purpose, including commercial use.

2. The data the server surfaces comes from the iFixit API and remains iFixit content under a non-commercial CC BY-NC-SA license. Commercial use of iFixit data requires contacting api@ifixit.com for pricing, and per iFixit's Terms of Service: "Training Large Language Models on iFixit content is prohibited."

This server is a read-only, on-demand lookup tool — like a search engine returning snippets, not bulk ingestion for training. It deliberately:

• Never bulk-downloads or persistently caches the guide corpus. Every request fetches on demand; the in-memory cache is bounded (256 entries) and mirrors iFixit's own CDN TTL (30 min).

• Has no LLM-training features — no dataset export, no bulk endpoints, no scraping modes.

• Attributes iFixit in the server description and every tool description (CC BY-NC-SA).

Your 0BSD rights cover the code only, not iFixit's content: keep your use of iFixit data non-commercial, and contact iFixit first if your use case is commercial or involves training.

Why this server?

Research found no existing iFixit MCP servers (see RESEARCH.md §8); this is the first server to cover the full public read surface of the iFixit API 2.0:

• Search across guides, wikis, questions, products (/suggest)

• Repair guides — summary or full detail, with steps, parts, and tools

• Device wiki pages — repairability scores (when iFixit has published one), featured guides, parts/tools counts

• Category tree — ~16 top-level categories down to nested sub-devices

• Maintenance schedules — battery/SSD health triggers and other upkeep tasks

• Media CDN URLs — images, videos, documents by id

• Contributor profiles — reputation, badges, and guide lists

• 8 tools, all anonymous and read-only — zero configuration, no API keys, no tokens

Related MCP server: Reddit MCP Server

Quick start

cd /home/kimbo/projects/ifixit-mcp
# Any Python 3.10+ venv works; this example uses the Hermes agent venv
/mnt/HC_Volume_105667182/kimbo/.hermes/hermes-agent/venv/bin/python3 -m pip install -e '.[dev]'

Run the server (stdio):

ifixit-mcp                                  # console script
# or
python -m ifixit_mcp.server                 # module entry point

Configuration

Hermes Agent

Add to your Hermes config.yaml:

mcp_servers:
  ifixit:
    command: /mnt/HC_Volume_105667182/kimbo/.hermes/hermes-agent/venv/bin/python3
    args: ['-m', 'ifixit_mcp.server']
    env:
      PYTHONPATH: /home/kimbo/projects/ifixit-mcp/src

Claude Desktop

Add to claude_desktop_config.json — no npx, no Node.js: this is a pure-Python stdio server:

{
  "mcpServers": {
    "ifixit": {
      "command": "/mnt/HC_Volume_105667182/kimbo/.hermes/hermes-agent/venv/bin/python3",
      "args": ["-m", "ifixit_mcp.server"],
      "env": {"PYTHONPATH": "/home/kimbo/projects/ifixit-mcp/src"}
    }
  }
}

Any Python 3.10+ interpreter works in place of the Hermes venv path, as long as the package is installed (or PYTHONPATH points at src/). No environment variables, API keys, or tokens are required for any tool.

Tool reference

All tools are read-only and anonymous. Errors are raised and delivered to the MCP client as error results with isError: true — never returned as success strings and never as stack traces. The wire message is Error executing tool <name>: <family prefix>: <reason> (e.g. Error executing tool get_guide: Guide lookup failed: Guide not found: 1220).

Response-size management

iFixit's raw API responses are far too large for LLM context budgets, so every tool compacts what it returns:

Beyond projection, the client keeps memory bounded:

• Bounded TTL cache — 256-entry in-memory cache, oldest entries evicted first. TTLs mirror iFixit's CDN edge TTL (observed x-debug-ttl: 1800): 30 min for guides/devices/categories/schedules/users, 1 hour for media. Entries are deep-copied on read and write so callers can never corrupt cached data (category-tree navigation reads the cached tree without copying — it is strictly read-only).

• Cache stampede protection — concurrent identical requests share one in-flight upstream call; a failed fetch clears its marker so retries work.

• Volatile endpoints never cached — search (/suggest) and paginated lists (/guides, /users/{id}/guides) bypass the cache entirely.

• No bulk access — there is no tool that enumerates the corpus; every tool is a targeted, on-demand lookup.

Development

Test-driven workflow: client behavior → server tool wiring → end-to-end tool tests.

# Install with dev dependencies
pip install -e '.[dev]'

# Run the full suite (542 tests)
pytest tests/ -v

Project layout:

ifixit-mcp/
├── src/ifixit_mcp/
│   ├── __init__.py
│   ├── client.py      # IfixitClient — async httpx client, all API logic
│   ├── launcher.py    # stdlib-only entry point: installs startup signal
│   │                  #   handlers before importing mcp, then delegates to
│   │                  #   server.main()
│   └── server.py      # FastMCP tool definitions (thin wrappers + projections)
├── tests/
│   ├── conftest.py
│   ├── test_client.py
│   ├── test_server.py
│   └── test_tools.py
├── RESEARCH.md        # API research findings (live-tested with curl)
├── openapi.json       # Official iFixit API 2.0 OpenAPI 3.1 spec (1.16 MB)
└── pyproject.toml

Architecture

LLM / MCP client
      │  (JSON-RPC over stdio)
      ▼
launcher.py ── stdlib-only console-script entry (ifixit-mcp command)
      │        • installs startup signal handlers BEFORE importing mcp
      │        • delegates to server.main()
      ▼
server.py  ── 8 × @mcp.tool() async wrappers
      │        • input validation, response projection
      │        • every exception → raised error (isError: true on the
      │          wire, message "<prefix>: <reason>", never a traceback)
      │        • lazy shared client (created on first tool call, closed at exit)
      ▼
client.py  ── IfixitClient (async httpx → https://www.ifixit.com/api/2.0)
              • descriptive User-Agent on every request (no fabricated URL)
              • bounded in-memory TTL cache (256 entries, deep-copied)
              • concurrency-safe rate limiter (0.5 s minimum interval, locked)
              • cache stampede dedup (one upstream call per concurrent key)
              • 429 retry with exponential backoff (honors Retry-After, capped at 8s, ≤3 retries)
              • error mapping: 400/401 → ValueError, 403 → ForbiddenError,
                404 → NotFoundError (both ValueError subclasses)
              • response compaction: _summarize_guide, _full_guide,
                _project_device, _compact_guide_item, _html_to_text

• launcher.py — the stdlib-only console-script entry (backing the ifixit-mcp command): installs startup signal handlers before the heavy mcp import, then delegates to server.main() (which re-installs the full close-client handler before serving). Import-footgun: importing ifixit_mcp.launcher (rather than running the ifixit-mcp command) installs process-wide SIGTERM/SIGINT handlers (os._exit(0)) as an import-time side effect, with no __main__ guard — library consumers embedding ifixit-mcp should import ifixit_mcp.server instead.

• Startup signals: a SIGTERM/SIGINT in the first ~100ms of interpreter bootstrap (before the module-top handler install runs) may hit the default disposition (exit -15); signals after startup are handled cleanly (exit 0, client closed).

• client.py — IfixitClient owns all HTTP, caching, rate limiting, retry, and response compaction. Every method validates its inputs before any network I/O, and translates 404s into per-resource messages (Guide not found: 1220, Device not found: iPhone, ...).

• server.py — a FastMCP server (ifixit) with 8 thin async tools. Each tool delegates to the client, applies the final compact projection (e.g. the 200-char search summary truncation), and converts every exception into a raised error (Error executing tool <name>: <prefix>: <reason> on the wire, isError: true). The server's instructions and every tool description carry the iFixit data attribution (CC BY-NC-SA).

Known limitations

• Every tool parameter is string-typed with explicit coercion: JSON numbers are coerced to strings and then validated (get_guide with guideid: 1220 works; search_guides with query: 0 searches for "0"); JSON booleans and junk types are rejected, and nulls are rejected for required params (omitted for optional ones) — all with clean family messages, never silent true → 1 fetches, searches for the literal "None", or raw pydantic dumps. The one residual library-level leak: FastMCP (mcp 1.26) exposes no validation-error hook, so a missing required parameter (e.g. calling search_guides with no arguments at all) still surfaces as FastMCP's own [type=missing] pydantic dump — there is no hook to intercept it. Everything the client or tool body can see is converted to a clean message.

License

This project has a dual license structure — the code and the data it serves are licensed separately:

• Code — the software in this repository is licensed under the 0-Clause BSD License (0BSD): free to use, copy, modify, and distribute for any purpose, with or without fee (SPDX: 0BSD). https://opensource.org/license/0bsd · the full text is in LICENSE.

• Data — the iFixit content surfaced through this server (guides, wiki pages, media, and other API responses) remains iFixit's content under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license: non-commercial use only, attribution required, and LLM training on iFixit content is prohibited per iFixit's Terms of Service. https://creativecommons.org/licenses/by-nc-sa/4.0/

The 0BSD grant covers the code only. This server is a read-only, on-demand lookup tool — it never bulk-caches the guide corpus, and nothing in the code license authorizes bulk-ingesting or training on iFixit content.

Links

• RESEARCH.md — full API research: endpoint inventory, verified response shapes, licensing analysis (§0)

• openapi.json — official iFixit API 2.0 OpenAPI 3.1 spec (56 paths, 53 schemas)

• iFixit API docs — official API documentation and licensing terms