Skip to main content
Glama

swift-docs-mcp

A local, read-only Model Context Protocol server that gives Claude Desktop search and retrieval over Apple's developer documentation (every framework in Apple's catalog, plus articles, sample code, tutorials and the Human Interface Guidelines) and swift.org's documentation (The Swift Programming Language, API Design Guidelines, SwiftPM, DocC, the Swift 6 migration guide, ...).

It is a documentation retrieval system, not an agent. It finds pages and returns their content faithfully (exact declarations, availability, deprecation, code listings), always with the source URL.

IMPORTANT

Unofficial project. Not affiliated with, endorsed by, or supported by Apple Inc. or the Swift project. Apple, Swift, Xcode, SwiftUI and other names are trademarks of Apple Inc. All documentation content belongs to its owners (Apple Inc., the Swift project). This tool fetches it on your machine for your own use. It does not host or redistribute it.

WARNING
  • Undocumented endpoints. It reads the JSON that Apple's and swift.org's documentation websites use internally. These are not public APIs and can change or disappear without notice; if that happens, the server reports errors (it never makes up content) until the code is updated.

  • Be polite to Apple's servers. Requests are limited to 1 per second and honour robots.txt. Please don't lower --interval-ms much, run builds in parallel, or use this for bulk mirroring.

  • First build is slow and large: about 20 minutes and about 300 MB on disk (~/Library/Caches/swift-docs-mcp).

  • Early software (v0.1). It has a large test suite and runs against the live sites, but it has only been used by its author. Expect rough edges.

Quick start (macOS)

Requires Node.js 22.18+ (node --version) and Claude Desktop.

git clone https://github.com/karimdiabb/swift-docs-mcp.git
cd swift-docs-mcp
npm install && npm run build      # build only; Claude Desktop starts the server itself
node dist/index.js index build    # one-time, about 20 min
which node                        # note this path for the config below

Then add it to Claude Desktop (Settings → Developer → Edit Config), using your own paths:

{
  "mcpServers": {
    "swift-docs": {
      "command": "/ABSOLUTE/PATH/FROM/which/node",
      "args": ["/ABSOLUTE/PATH/TO/swift-docs-mcp/dist/index.js"]
    }
  }
}

Quit Claude Desktop with ⌘Q, reopen it, and ask something like "Use swift-docs: what's the declaration of NavigationStack?". If macOS asks whether node may access a folder (for example because you cloned into ~/Desktop or ~/Documents), click Allow: node needs to read the server's own files. Details are in sections 7 and 12.

Related MCP server: DevDocs MCP Server

1. Purpose and scope

  • Search a local index of about 380,000 Apple documentation pages built from Apple's own catalog.

  • Retrieve any page live from Apple as structured Markdown, cached locally for 7 days.

  • Look up one API symbol and get its declaration(s), parameters, availability and parent. If the name is ambiguous, you get the candidates instead of a guess.

  • Report coverage honestly: what is indexed, how fresh it is, and what is not covered.

Out of scope: AI summaries in place of source text, editing code, reading your projects, Xcode automation, hosted services, accounts, telemetry.

2. Architecture

Claude Desktop ──stdio──▶ dist/index.js (MCP server, 4 read-only tools)
                              │
           ┌──────────────────┼────────────────────┐
           ▼                  ▼                    ▼
   local index (SQLite   page retrieval        status report
   FTS5, node:sqlite)    DocService
           ▲                  │ cache (7 days, ETag revalidation, atomic files)
           │                  ▼
   index build/refresh   AppleClient: HTTPS only, developer.apple.com only, /tutorials/data/ only,
   (CLI, explicit)       1 request/s, timeouts, size cap, every redirect re-checked

Path

Role

src/security/url.ts

URL canonicalization and the host/path allowlist

src/apple/client.ts

Paced, locked-down HTTP client with conditional requests

src/apple/docc-parser.ts, markdown.ts

DocC JSON → page model → Markdown (incl. Objective-C variants, REST, tutorials)

src/apple/docs.ts

Retrieval: cache → Apple (304 revalidation) → parse

src/cache/cache.ts

On-disk page cache

src/index/

Navigator parser, SQLite store, build/refresh/enrich

src/tools/, src/server.ts

MCP tools and stdio server

src/cli.ts

index build/refresh/enrich/status, cache clear, doc

3. Documentation coverage and known gaps

Covered: every root listed in Apple's catalog (technologies.json, about 400 frameworks and collections), through their navigator indexes. This includes API reference for all symbol kinds (Swift and Objective-C, REST endpoints, JSON objects, property-list keys), articles, sample-code pages and collections. The Human Interface Guidelines and a few nested collections without an index are covered by walking their page links. Tutorial collections are discovered through links (plus a seed, /tutorials/swiftui). From docs.swift.org, every collection in its navigator index is included (the Swift book, API Guidelines, Package Manager, DocC, Embedded Swift, platform guides, compiler diagnostics, the Swift 6 migration guide, ...), except those Apple's catalog already has (Standard Library, Testing): Apple's copies are used for those.

Known gaps (also reported by get_apple_docs_status):

  • Apple publishes no verified, complete inventory of its documentation, so coverage is "everything Apple's own catalog and indexes list", not a proven 100%.

  • Abstracts, platforms and declarations are only stored for pages fetched at least once (on demand, or with index enrich). Until then, search shows title, kind and framework. The platform filter drops pages known not to support the platform, lists confirmed pages first, and marks the rest "availability not yet known".

  • Tutorials have no catalog endpoint; only linked or seeded tutorial collections are found.

  • Not included: the retired Documentation Archive (/library/archive), localized docs, WWDC videos, forums.

  • Sample-code download links aren't generated (the download host is unverified); the sample's page is linked.

4. Apple sources and discovery method

Requests go to exactly two hosts:

Host

Endpoint

Use

Status

developer.apple.com

/tutorials/data/documentation/technologies.json

Root catalog

observed, undocumented

developer.apple.com

/tutorials/data/index/<root>

Navigator index: every page of a root

observed, undocumented

developer.apple.com

/tutorials/data/<page path>.json

DocC JSON of one page

observed, undocumented

docs.swift.org

/latest/index/index.json

Navigator for all swift.org collections

observed, undocumented

docs.swift.org

/latest/data/<page path>.json

DocC JSON of one page

observed, undocumented

docs.swift.org has no robots.txt; /swift-book/... URLs redirect to /latest/... and are accepted as aliases.

Apple's search (/search/) is disallowed by robots.txt and is not used; search runs on the local index. Requests honour robots.txt, are spaced at least 1 second apart, and identify themselves with a clear User-Agent. DocC's JSON formats come from Apple's open-source swift-docc. Apple's hosting of them is not a public API and could change; the server reports such failures as errors, never as empty results.

5. Requirements

  • macOS (any recent version) with Claude Desktop.

  • Node.js 22.18 or newer (node --version). It uses the built-in node:sqlite; nothing else is native.

  • About 400 MB of disk for the index and cache, and network access to developer.apple.com.

6. Installation and build

cd /path/to/swift-docs-mcp
npm install
npm run build          # compiles to dist/ (it only builds; Claude Desktop starts the server itself)
npm test               # optional: unit tests, no network

7. Claude Desktop configuration

  1. Find the absolute paths you need:

    which node                       # YOUR node path; it differs per Mac (Homebrew, nvm, nodejs.org installer)
    echo "$PWD/dist/index.js"        # run inside the project folder
  2. Open the config file. In Claude Desktop: Settings → Developer → Edit Config. On macOS it is currently ~/Library/Application Support/Claude/claude_desktop_config.json (the location may change between Claude Desktop versions; use the menu if in doubt):

    open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
  3. Add the server (merge with any existing mcpServers):

    {
      "mcpServers": {
        "swift-docs": {
          "command": "/ABSOLUTE/PATH/FROM/which/node",
          "args": ["/ABSOLUTE/PATH/TO/swift-docs-mcp/dist/index.js"]
        }
      }
    }

    Check it starts: "$(which node)" dist/index.js should print swift-docs-mcp 0.1.0 ready and then wait (it expects Claude to talk to it); stop it with Ctrl-C.

  4. Quit Claude Desktop completely (⌘Q) and reopen it. The four tools appear under the tools (🔨) menu.

  5. Build the index (section 9). Retrieval by URL works before that; search needs the index.

8. MCP tools

Tool

Inputs

Returns

search_apple_docs

query; optional framework, platform (iOS, iPadOS, macOS, watchOS, tvOS, visionOS, Mac Catalyst), kind (api, article, tutorial, sample_code, guideline, collection, other), limit (≤30), cursor

Ranked results: title, kind, framework, symbol name, URL, and abstract/declaration/availability when known

get_apple_doc

url; optional include_related (default true), max_related (default 10, ≤30)

The full page as Markdown, with source URL, retrieval time and cache status

get_apple_api_details

symbol; optional framework, platform

Declaration(s), kind, parameters, return value, availability, deprecation, parent, related symbols, URL; or a candidate list if ambiguous

get_apple_docs_status

none

Sources, search mode, index freshness and counts, frameworks/platforms, cache, known gaps, recent errors

Example calls (what Claude sends):

{"name": "search_apple_docs", "arguments": {"query": "navigation stack", "framework": "SwiftUI"}}
{"name": "get_apple_doc", "arguments": {"url": "https://developer.apple.com/documentation/swiftui/navigationstack"}}
{"name": "get_apple_doc", "arguments": {"url": "https://developer.apple.com/documentation/foundation/nsstring?language=objc"}}
{"name": "get_apple_doc", "arguments": {"url": "https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency"}}
{"name": "get_apple_api_details", "arguments": {"symbol": "View.onAppear"}}
{"name": "get_apple_api_details", "arguments": {"symbol": "frame(width:height:alignment:)"}}
{"name": "get_apple_docs_status", "arguments": {}}

9. Initial index creation

Building is a deliberate step. The server never crawls on startup.

node dist/index.js index build        # about 15-25 minutes at 1 request/second
node dist/index.js index status       # check what was indexed

It reads Apple's catalog, downloads about 400 navigator indexes (about 140 MB, not kept), walks the roots that have no index, and writes index.sqlite. If it is interrupted, run it again: the status will say the last sync was interrupted.

10. Index refresh, enrichment and cache clearing

node dist/index.js index refresh                     # conditional requests: unchanged roots cost one 304 each
node dist/index.js index refresh --only swiftui,uikit
node dist/index.js index refresh --only swift.org    # just docs.swift.org
node dist/index.js index enrich                      # fill abstracts/platforms/declarations for top-level
                                                     # pages (struct, class, protocol, enum, article, ...)
node dist/index.js index enrich --framework swiftui --max 500
node dist/index.js cache clear                       # delete cached pages (the index is kept)
node dist/index.js doc https://developer.apple.com/documentation/swiftui/view   # print one page

Data lives in ~/Library/Caches/swift-docs-mcp/ (index.sqlite, pages/). Set SWIFT_DOCS_MCP_HOME to use another absolute path. A refresh never deletes pages because of a failed request. A root whose new index would remove more than half of its pages is refused and flagged as partial. Pages that disappear are kept as "removed" and come back if Apple lists them again. Run index refresh weekly or so; pages fetched through the tools revalidate themselves after 7 days.

enrich is optional. Top-level kinds are about 41,000 pages, roughly 11 hours at 1 request/second. You can run it in chunks with --max, and it skips pages already done.

11. Security model and permissions

  • Read-only and narrow. No shell commands, no reading of arbitrary files or projects, no writes except its own data directory, no network port (stdio only), no credentials, and the only environment variables it reads are SWIFT_DOCS_MCP_HOME and XDG_CACHE_HOME.

  • No arbitrary URLs. Inputs must be https://developer.apple.com documentation, HIG or tutorial pages, or https://docs.swift.org/latest/documentation/... pages. The raw input is checked before URL parsing (dot segments, encoded slashes and backslashes, control characters). The host must match exactly, so lookalikes, IP literals, subdomains, credentials and ports are rejected. Requests can only go to /tutorials/data/ on Apple's host and /latest/data/ or /latest/index/ on docs.swift.org, and robots-disallowed paths are refused.

  • Redirects are followed manually (at most 3) and every hop is re-validated.

  • Limits: 20-second timeout, 25 MB response cap enforced while streaming, at least 1 second between requests, identical in-flight requests shared.

  • Input validation: every tool argument is validated with strict Zod schemas (unknown keys rejected).

  • Content as data: retrieved pages are marked as reference content, not instructions. Images and videos are links only; nothing downloaded is executed.

  • Logs go to stderr only; stdout carries only MCP messages (checked by a test that launches the server).

12. Troubleshooting

Symptom

Fix

Tools don't appear in Claude Desktop

Check the JSON is valid, the paths are absolute, then fully quit (⌘Q) and reopen. Logs: ~/Library/Logs/Claude/mcp*.log.

"spawn node ENOENT" or "No executable file at …"

The command path is wrong for your Mac: put the output of which node there.

Search says the index is not available

Run node dist/index.js index build. The server picks up the new index without a restart.

"Apple could not be reached"

Network or Apple outage. Cached pages are still served, with a warning and their date.

index build says another operation is running

Another build/refresh is running. If none is, the lock is from a crashed run and the next run takes it over.

Status shows roots with error/partial

Run index refresh later; errors are per root and don't affect the rest.

ExperimentalWarning: SQLite is an experimental feature

Harmless (stderr). node:sqlite is marked experimental in Node 22.

"Server disconnected" after a macOS "node would like to access…" popup you denied

System Settings → Privacy & Security → Files & Folders → enable the folder for node (or Claude). If it isn't listed: tccutil reset SystemPolicyDesktopFolder (or …DocumentsFolder), restart Claude and click Allow. Or clone outside protected folders, e.g. ~/Developer.

Results look stale

node dist/index.js index refresh; for one page, cache clear or wait for the 7-day revalidation.

13. Limitations and endpoint stability

  • The JSON endpoints are what Apple's documentation website uses internally. They are stable in practice (DocC format), but undocumented: Apple can change them without notice. If that happens, errors appear in get_apple_docs_status and index status, and the parser and discovery code need updating.

  • Ranking is local full-text ranking (bm25 with boosts for exact symbol names and top-level types). It is not Apple's ranking.

  • Coverage limits are listed in section 3.

Test fixtures

tests/fixtures/ contains a small number of real documentation pages (DocC JSON) downloaded from developer.apple.com and docs.swift.org on 2026-11-09. They exist only so the parser can be tested against the real format offline. Their content belongs to Apple Inc. and the Swift project, and they are not covered by anything in this repository. If you are a rights holder and want them removed, please open an issue.

License

MIT: use, copy, modify and share the code freely. This covers the project's own code only, not the Apple and swift.org content in tests/fixtures/ (see above).

Development

npm test                      # unit tests (mocked HTTP, no network)
npm run typecheck
npm run test:integration      # opt-in: real Apple pages across ~20 framework families, a small real index,
                              # and the built server over stdio (run `npm run build` first)
npm run doc -- <url>          # render one page from source (no build needed)

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides AI agents with instant access to official Apple developer documentation, Swift programming guides, design guidelines, and Apple Developer YouTube content including WWDC sessions. Uses advanced RAG technology with semantic search and AI reranking to deliver accurate, contextual answers for Apple platform development.
      7
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides access to 600+ documentation libraries from DevDocs.io including Python, JavaScript, React, Django, and more. Enables searching, browsing, and retrieving documentation content directly through Claude Desktop.
      5
      6
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides access to Apple's official developer documentation, frameworks, APIs, and WWDC session transcripts across all Apple platforms. It enables AI assistants to search technical guides, sample code, and platform compatibility information using natural language queries.
      18
      1,052 npm
      1,384
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides access to Apple documentation and WWDC transcripts with semantic, keyword, and hybrid search capabilities, enabling developers to quickly find relevant code examples and technical information.
      121
      MIT