AppleRef MCP – Documentação Apple Offline
nzrsky/appleref-mcp
Documentação Apple offline para Claude e agentes LLM
Ver no GitHubServidor MCP que fornece acesso offline completo à documentação de API do Apple, lendo direto de um docset no formato Dash. Elimina dependência de scraping ou de rede para consultar APIs do ecossistema Apple durante desenvolvimento.
Instalação
npx convez-ai nzrsky/appleref-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar APIs Apple (iOS, macOS, Swift) sem internet
- Assistir desenvolvimento de apps nativos com contexto preciso de referência
- Integrar documentação oficial Apple a workflows de IA sem latência de rede
Veredito

Ferramenta especializada e bem pensada para quem desenvolve no ecossistema Apple com suporte a IA. O design offline + auto-download eficiente resolve um problema real de latência e confiabilidade em buscas de referência.
README
A tradução para o português deste README ainda está na fila.
appleref-mcp
Offline MCP server for Apple Developer Documentation, reading directly from a
Dash-format Apple_API_Reference.docset. No network calls, no Dash.app required —
just the .docset directory on disk.
Why
LLM agents working on Apple platforms need accurate, current API documentation,
but developer.apple.com is heavy JS, scrapers fight TLS quirks, and Apple's docs
aren't shipped in Xcode anymore. Dash maintains a complete, regularly-updated
offline mirror as a single self-contained docset bundle. This server reads that
bundle directly.
Requirements
-
Python 3.11+
-
An
Apple_API_Reference.docsetdirectory. By default the server downloads a packed copy (~350 MB compressed, ~1.4 GB on disk) from this repo's GitHub releases on first run — no Dash needed.If you'd rather supply your own, install Dash and download the Apple API Reference docset; the bundle lives at:
~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docsetThe server uses it automatically from that path, or from anywhere you point
APPLEREF_DOCSETat. Dash doesn't need to be running.
Install
Pick the option that fits your workflow.
Run straight from GitHub (no install)
uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp
Install as a uv tool (recommended)
uv tool install git+https://github.com/nzrsky/appleref-mcp
appleref-mcp # binary on your PATH
To upgrade later: uv tool upgrade appleref-mcp.
From a local checkout
git clone https://github.com/nzrsky/appleref-mcp.git
cd appleref-mcp
uv tool install --from . appleref-mcp
# or, for hacking:
uv sync && uv run appleref-mcp
Configure docset location
The server looks for the docset in this order:
APPLEREF_DOCSETenvironment variable (path to the.docsetdirectory, or its parent)./Apple_API_Reference.docset~/Library/Application Support/Dash/DocSets/Apple_API_Reference/Apple_API_Reference.docset~/Apple_API_Reference.docset~/.cache/appleref-mcp/Apple_API_Reference.docset(auto-download cache)
If none of those exist, the server downloads the latest packed docset from this repo's GitHub releases into the cache directory on first run, then operates fully offline from then on.
| env var | default | purpose |
|---|---|---|
APPLEREF_DOCSET | unset | explicit docset path (highest priority) |
APPLEREF_AUTO_DOWNLOAD | 1 | set to 0 to disable the GitHub fallback |
APPLEREF_CACHE_DIR | ~/.cache/appleref-mcp | where the auto-downloaded docset lives |
APPLEREF_RELEASE_REPO | nzrsky/appleref-mcp | source repo for the release asset |
APPLEREF_RELEASE_TAG | latest docset-* | pin to a specific release |
Wire it up to Claude Code
The fastest path uses uvx so nothing needs to be installed up front:
claude mcp add appleref -- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp
If your docset isn't in the default Dash location, pass APPLEREF_DOCSET:
claude mcp add appleref \
--env APPLEREF_DOCSET=/path/to/Apple_API_Reference.docset \
-- uvx --from git+https://github.com/nzrsky/appleref-mcp appleref-mcp
After adding, restart Claude Code and verify:
claude mcp list # should show 'appleref'
# or, in a Claude Code session:
/mcp # interactive view of connected servers
If you installed via uv tool install, swap the command for the bare binary:
claude mcp add appleref -- appleref-mcp
Manual MCP config (other clients)
{
"mcpServers": {
"appleref": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/nzrsky/appleref-mcp",
"appleref-mcp"
],
"env": {
"APPLEREF_DOCSET": "/path/to/Apple_API_Reference.docset"
}
}
}
}
Quick smoke test
Without a Claude client, you can drive the server directly over stdio:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| appleref-mcp
You should see two JSON-RPC responses listing the four tools.
Tools
| Tool | Purpose |
|---|---|
search_apple_docs(query, language?, framework?, type?, limit?) | Find symbols by name. |
get_apple_doc(query, language?, framework?) | Return a full documentation page as markdown. Accepts a name or a canonical path. |
list_frameworks(filter?) | List indexed frameworks. |
list_types() | List symbol kinds with counts. |
language is "swift" (default) or "objc".
How it works
The Dash docset stores documentation in two SQLite databases plus a directory of brotli-compressed files:
Contents/Resources/optimizedIndex.dsidx ← name → URL index (FTS4)
Contents/Resources/Documents/cache.db ← uuid → (data_id, offset, length)
Contents/Resources/Documents/fs/<data_id> ← brotli(concatenated DocC RenderJSON)
For a given symbol path:
canonical = "/documentation/swiftui/griditem"
uuid = lang_prefix + base64url(sha1(canonical)[:6]).rstrip("=")
(lang_prefix is "ls" for Swift, "lc" for ObjC)
→ refs WHERE uuid=? → (data_id, offset, length)
→ brotli.decompress(fs/<data_id>)[offset:offset+length] = DocC JSON
The server renders the JSON to markdown and returns it.
Development
uv sync
uv run pytest -v
Tests run end-to-end against a real docset and skip cleanly if none is available.
Publishing a new docset release
Maintainer-only. Requires a local Dash with the Apple API Reference docset downloaded.
# 1. pack — writes dist/appleref-docset-<tag>.tar.xz + .sha256 + .notes.md
./tools/pack-docset.sh
# 2. publish — prints the exact gh command at the end of step 1; e.g.
gh release create docset-24500-79 \
--title 'Apple docset 24500-79' \
--notes-file dist/appleref-docset-24500-79.notes.md \
dist/appleref-docset-24500-79.tar.xz \
dist/appleref-docset-24500-79.tar.xz.sha256
The MCP server picks up the new release automatically on its next first-run install (or when the cache directory is cleared).
License
MIT