apple-docs-mcp

An MCP server and CLI that search Apple Developer Documentation from Xcode's on-disk documentation index — fully offline, no network calls.

Coding agents recall Apple APIs from training data that lags the installed SDK. This server gives them the real text: signatures, availability, and code examples, straight from the documentation that Xcode already downloaded.

Why this exists

Xcode installs a local copy of the Apple Developer Documentation asset. It looks like a source an agent could read directly, but the prose is not readable in place:

• index/index.json (104 MB) holds navigation nodes — path, title, type — and no prose. The keys abstract, declarationFragments, and primaryContentSections appear zero times.

• cache.db stores 1269 compressed blobs whose header (9b21f31f) decodes under none of LZ4, LZFSE, zlib, LZMA, or LZBITMAP via Apple's libcompression.

• documentation-db/index.sql (1.2 GB) is a vector store for Xcode's own semantic search, not text.

Xcode 27 exposes an MCP service with a DocumentationSearch tool that answers from this asset. Measured behavior: 19–20 documents per query with full contents and code examples, ~0.4 s median latency, and zero bytes of network traffic. This project wraps that tool so any MCP client can use it, and adds an offline framework index that needs no approval at all.

Related MCP server: Apple Deep Docs MCP

Install

Requires macOS, Xcode installed, and uv.

git clone https://github.com/Ahmetshbzz/apple-docs-mcp
cd apple-docs-mcp
uv sync

Install the CLI on your PATH:

uv tool install --editable .

Register with an MCP client

Claude Code:

claude mcp add apple-docs --scope user -- \
  uv run --quiet --project /path/to/apple-docs-mcp apple-docs-mcp

Codex (~/.codex/config.toml):

[mcp_servers.apple-docs]
command = "uv"
args = ["run", "--quiet", "--project", "/path/to/apple-docs-mcp", "apple-docs-mcp"]
startup_timeout_sec = 60

Tools

CLI

apple-docs search "SwiftData model inheritance" --framework SwiftData
apple-docs search "AVAudioSession category" --json
apple-docs frameworks
apple-docs status

Exit codes are distinct per failure so scripts can branch: 0 success, 1 usage, 2 not approved, 3 Xcode unavailable, 4 timeout, 5 protocol, 6 asset missing.

The approval dependency

This is the one thing to understand before using it.

search_docs drives mcpbridge, so Xcode must be running with an approved workspace:

xcrun mcp-server open <path-to-project>   # accept the dialog in Xcode

• Approval is granted per process, not per user. A different interpreter needs its own approval.

• Approval expires after 24 hours.

• Approval requires an open workspace; the documentation search itself is global, so any project works.

Every failure returns a typed error with a remedy. The tool never returns an empty list to signal a problem, because an empty result is indistinguishable from "this API does not exist" — the exact confusion it exists to prevent.

list_frameworks reads index.json directly and needs none of this.

Development

uv run pytest tests/                 # 37 tests
uv run pytest tests/ -m integration  # live bridge tests
uv run ruff check src tests

Unit tests need no Xcode. Integration tests skip themselves when the bridge is absent or unapproved.

Architecture

One implementation, two interfaces. Business logic is not duplicated.

src/apple_docs_mcp/
├── bridge.py      # mcpbridge JSON-RPC client; owns the protocol and typed errors
├── frameworks.py  # offline index.json reader
├── responses.py   # shared JSON payload contract
├── cli.py         # argparse adapter
└── server.py      # MCP adapter

Verified environment

Measured 2026-09-17, not assumed:

License

MIT — see LICENSE.