swift-docs-mcp
Provides search and retrieval over Apple's developer documentation, including frameworks, API symbols, articles, sample code, tutorials, and Human Interface Guidelines, returning faithful Markdown content with source URLs.
Provides search and retrieval over swift.org documentation, including The Swift Programming Language, API Design Guidelines, Swift Package Manager, DocC, and the Swift 6 migration guide.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
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.
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-msmuch, 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 belowThen 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-checkedPath | Role |
| URL canonicalization and the host/path allowlist |
| Paced, locked-down HTTP client with conditional requests |
| DocC JSON → page model → Markdown (incl. Objective-C variants, REST, tutorials) |
| Retrieval: cache → Apple (304 revalidation) → parse |
| On-disk page cache |
| Navigator parser, SQLite store, build/refresh/enrich |
| MCP tools and stdio server |
|
|
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. Theplatformfilter 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 |
| Root catalog | observed, undocumented |
developer.apple.com |
| Navigator index: every page of a root | observed, undocumented |
developer.apple.com |
| DocC JSON of one page | observed, undocumented |
docs.swift.org |
| Navigator for all swift.org collections | observed, undocumented |
docs.swift.org |
| 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-innode: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 network7. Claude Desktop configuration
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 folderOpen 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.jsonAdd 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.jsshould printswift-docs-mcp 0.1.0 readyand then wait (it expects Claude to talk to it); stop it with Ctrl-C.Quit Claude Desktop completely (⌘Q) and reopen it. The four tools appear under the tools (🔨) menu.
Build the index (section 9). Retrieval by URL works before that; search needs the index.
8. MCP tools
Tool | Inputs | Returns |
|
| Ranked results: title, kind, framework, symbol name, URL, and abstract/declaration/availability when known |
|
| The full page as Markdown, with source URL, retrieval time and cache status |
|
| Declaration(s), kind, parameters, return value, availability, deprecation, parent, related symbols, URL; or a candidate list if ambiguous |
| 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 indexedIt 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 pageData 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_HOMEandXDG_CACHE_HOME.No arbitrary URLs. Inputs must be
https://developer.apple.comdocumentation, HIG or tutorial pages, orhttps://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: |
"spawn node ENOENT" or "No executable file at …" | The |
Search says the index is not available | Run |
"Apple could not be reached" | Network or Apple outage. Cached pages are still served, with a warning and their date. |
| 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 | Run |
| Harmless (stderr). |
"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: |
Results look stale |
|
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_statusandindex 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and read Apple developer documentation, HIG, and WWDC transcripts as Markdown.
Apple developer docs and WWDC transcripts with RAG retrieval and Jev relevance ranking.
Search and read the Claude Platform documentation and API reference.
Search the official docs of Claude Code, Cursor, OpenAI Codex and MCP, refreshed daily.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceProvides 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-
- AlicenseAqualityDmaintenanceProvides 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.56MIT
- AlicenseAqualityDmaintenanceProvides 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.181,052 npm1,384MIT
- AlicenseNot gradedqualityBmaintenanceProvides 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.121MIT