Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@apple-design-mcp Search the HIG for 'touch targets' and show the top result"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Live Apple Human Interface Guidelines as a CLI and MCP server.
Apple’s HIG site is JavaScript-rendered, so agents cannot read it directly. This package fetches Apple’s DocC JSON and renders it as Markdown — Getting started, Foundations, Patterns, Components, Inputs, and Technologies — for iOS, iPadOS, macOS, tvOS, visionOS, and watchOS.
It does not vendor Apple’s text. Pages are fetched live and cached on disk.
git
macOS, Linux, or Windows
Related MCP server: Apple RAG MCP
git clone https://github.com/rncrosby/apple-design-mcp.git
cd apple-design-mcp
npm installnpm install also builds dist/ (prepare runs tsc).
Put the CLI on your PATH (pick one):
# This machine only, from the clone
npm link
# Or install the clone globally
npm install -g .That exposes three names for the same binary: hig, apple-design, and apple-design-mcp.
Check it:
hig --help
hig toc
hig get color
hig search "touch targets"Without linking, run it from the clone:
node dist/cli.js toc
npm start # starts the MCP server on stdioOptional: cache every HIG page so search is local and fast:
hig syncCache location: ~/Library/Caches/apple-design-mcp on macOS, $XDG_CACHE_HOME/apple-design-mcp or ~/.cache/apple-design-mcp on Linux. Override with APPLE_DESIGN_CACHE.
The server speaks stdio. After npm install in the clone, the entrypoint is dist/cli.js mcp.
In every snippet below, replace /ABS/PATH/apple-design-mcp with the absolute path to your clone (for example /Users/you/Developer/apple-design-mcp).
If you already ran npm link / npm install -g ., you can use the global binary instead:
{ "command": "hig", "args": ["mcp"] }command = "hig"
args = ["mcp"]Restart the client after editing config.
This repo: already includes .cursor/mcp.json. Open the clone in Cursor, run npm install, then Cursor Settings → MCP and enable apple-design.
Any project / globally: create or edit .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects):
{
"mcpServers": {
"apple-design": {
"command": "node",
"args": ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
}
}
}Cursor UI: Settings → Cursor Settings → MCP → Add new global MCP server, then paste the same JSON.
Grok models inside Cursor use this same Cursor MCP config. You do not add a separate Grok entry in Cursor.
From the clone:
claude mcp add --transport stdio apple-design -- node dist/cli.js mcpFrom a global install:
claude mcp add --transport stdio apple-design -- hig mcpOr commit .mcp.json (already in this repo) so Claude Code picks it up for this project. Approve the server when Claude Code prompts.
Claude Desktop — edit:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"apple-design": {
"command": "node",
"args": ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
}
}
}Quit and reopen Claude Desktop.
CLI:
codex mcp add apple-design -- node /ABS/PATH/apple-design-mcp/dist/cli.js mcpOr edit ~/.codex/config.toml (global) or .codex/config.toml in a project (this repo already has one):
[mcp_servers.apple-design]
command = "node"
args = ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]Codex CLI, the IDE extension, and the Codex desktop app share ~/.codex/config.toml. In a session, run /mcp to confirm apple-design is connected.
Grok reads ~/.grok/config.toml globally, and .grok/config.toml in a project (this repo already has one).
[mcp_servers.apple-design]
command = "node"
args = ["/ABS/PATH/apple-design-mcp/dist/cli.js", "mcp"]
startup_timeout_sec = 30If the Grok CLI supports it:
grok mcp add apple-design -- node /ABS/PATH/apple-design-mcp/dist/cli.js mcpGrok also loads Claude Code’s .mcp.json / ~/.claude.json when present, so configuring Claude Code in this clone is enough for Grok in the same directory.
Tool | Purpose |
| Search the HIG ( |
| Fetch one page as Markdown (slug, title, path, or Apple URL) |
| Full table of contents |
| List topics, optionally in a section ( |
Resources: hig://toc, hig://{slug} (for example hig://color). Prompt: hig_review.
Typical flow: hig_search → hig_get the best slug → cite the Apple URL.
The first full-text search that misses on titles downloads every HIG page into the local cache (or run hig sync once). After that, search is local and fast.
hig toc
hig list Foundations
hig get color
hig get buttons --json
hig search "touch targets" --platform ios
hig sync
hig cache
hig mcpimport { HigClient } from "apple-design-mcp";
const hig = new HigClient();
const hits = await hig.search("Liquid Glass");
const page = await hig.get("materials");
console.log(page.markdown);npm install
npm test
npm run buildMIT for this software. Human Interface Guidelines content is © Apple Inc. Canonical source: developer.apple.com/design/human-interface-guidelines. This project is not affiliated with Apple.
Fetch one Human Interface Guidelines page as Markdown. Pass a slug (color, buttons), title, path, or developer.apple.com URL.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Slug, title, path, or URL, e.g. 'buttons', 'designing-for-ios', or '/design/human-interface-guidelines/color' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety. The description adds the output format (Markdown) and clarifies accepted input types, which is useful but does not go beyond basics like error behavior, acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the core action front-loaded and the input specification clearly stated in the second sentence. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema, the description covers what it does, what it returns, and how to specify the topic. It omits error handling details, but those are minor for this simple scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the topic parameter with examples and coverage is 100%, so the baseline is 3. The description adds mention of developer.apple.com URLs and repeats slug examples, but adds little new semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one Human Interface Guidelines page as Markdown', specifying the verb and resource. It does not explicitly differentiate from sibling tools like hig_search or hig_toc, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs to pass a slug, title, path, or developer.apple.com URL, which guides input usage. However, it does not mention when to use this tool over alternatives, leaving the choice implied (e.g., use when you have a specific page identifier).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List HIG topics, optionally limited to a section such as Foundations, Components, Patterns, Inputs, Technologies, or Getting started.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Section name, e.g. Foundations, Components, Patterns, Inputs, Technologies, Getting started |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is clear. The description adds that it lists topics and can be filtered by section, but it doesn't disclose details like whether the list is ordered, paginated, or if it returns full objects or just summaries. With annotations covering key behaviors, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main verb and resource, then adds the optional parameter. Every word earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with one optional parameter and no output schema, the description is sufficient. It covers the purpose and the filter, and combined with annotations (read-only, open-world), an agent has enough to call it. The only minor gap is not describing the return format, but that's minor given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the 'section' parameter with examples. The description adds the context that the section filters the list and lists possible values, which is slightly beyond the schema's 'e.g.' but still minimal. Baseline 3 is correct since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List') and resource ('HIG topics'), and it mentions it can be optionally limited by section, which helps distinguish from sibling tools like hig_get. However, it doesn't explicitly differentiate from hig_toc, which might also list topics, so it's clear but not fully differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to list topics, optionally filtered by section), but it doesn't provide explicit guidance on when to use alternatives like hig_search or hig_get. It mentions the optional section filter, which gives some context for usage, but lacks exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Apple's Human Interface Guidelines by topic, component, pattern, or design question (e.g. 'touch targets', 'tab bars', 'Liquid Glass').
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 8) | |
| query | Yes | Natural-language search query | |
| platform | No | Limit results to a platform: ios, ipados, macos, tvos, visionos, watchos |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is covered. The description adds that it accepts natural-language queries and can filter by topic/component/pattern, but it does not disclose details like result ranking, pagination, or how the search handles broad queries. This is acceptable given the annotations, but not rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and resource, then provides concrete examples. Every word earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with full schema coverage and read-only/idempotent annotations, the description is nearly complete. It could mention that results are returned as a list or that the query is free-form, but the examples already convey that. The lack of an output schema is not a gap because the description's job is not to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (query, limit, platform). The description adds the notion of natural-language queries and examples, but it does not add significant meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search') and resource ('Apple's Human Interface Guidelines') and clarifies the scope with examples of topics ('touch targets', 'tab bars', 'Liquid Glass'). It clearly distinguishes this from sibling tools like hig_get or hig_toc by indicating it is a search operation over the guidelines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you have a topic, component, pattern, or design question. It does not explicitly state when not to use it or name alternatives like hig_get or hig_toc, but the examples and phrasing provide clear context for a search-oriented use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the full Human Interface Guidelines table of contents (Getting started, Foundations, Patterns, Components, Inputs, Technologies).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds that it returns the full table of contents with major sections, which is useful but not deeply detailed. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no waste. It front-loads the core action (return) and the resource (table of contents) followed by a parenthetical list of sections. Ideal length for a zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, zero-parameter tool with openWorldHint and idempotentHint, the description is complete enough. An agent knows exactly what to expect from the call. No output schema, but the description implies a structured list of sections, which is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters)Skip means there's nothing to explain beyond the schema. With 100% schema coverage and no params, a baseline 4 is appropriate, and the description doesn't need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the full HIG table of contents and lists the main sections. This is a specific verb and resource, distinguishing it from siblings like hig_search, hig_get, and hig_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool to get an overview of the entire HIG structure, contrasted with siblings that likely search or retrieve specific items. It doesn't explicitly state when not to use it, but the context is clear. No exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0hig_gethig_listhig_searchhig_tocScored across 4 tools
The four tools are mostly distinct: search, get specific page, full TOC, and list topics. There is slight overlap between hig_toc (full TOC) and hig_list (optional section listing), but descriptions clarify the difference, making misselection unlikely.
All tools share the 'hig_' prefix followed by a clear action or noun (search, get, toc, list). The pattern is perfectly consistent and predictable, using lowercase with underscores throughout.
With only 4 tools, the server is tightly scoped to browsing and retrieving HIG content. Each tool serves a distinct, necessary function—search, fetch, TOC, and listing—without redundancy or bloat.
The tool set covers the core HIG browsing workflow: finding topics, listing sections, and retrieving full pages. A minor gap is the lack of a bulk-fetch-all-pages-in-section tool, but the existing list and get tools can accomplish that indirectly.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Web data tools for AI agents: pages as markdown, search, maps, commerce, jobs, AI answers.
Search, fetch (with provenance), scan, and convert AI instruction files for agents.
The documentation, as a tool your agent can call: 950+ AI-dev guides. Search + fetch tools.
