apple-design-mcp

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.

Requirements

• Node.js 20+

• git

• macOS, Linux, or Windows

Related MCP server: Apple Dev MCP Server

Clone and install the CLI

git clone https://github.com/rncrosby/apple-design-mcp.git
cd apple-design-mcp
npm install

npm 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 stdio

Optional: cache every HIG page so search is local and fast:

hig sync

Cache 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.

Add the MCP server

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.

Cursor

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.

Claude (Claude Code)

From the clone:

claude mcp add --transport stdio apple-design -- node dist/cli.js mcp

From a global install:

claude mcp add --transport stdio apple-design -- hig mcp

Or 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.

Codex

CLI:

codex mcp add apple-design -- node /ABS/PATH/apple-design-mcp/dist/cli.js mcp

Or 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 (Grok CLI / Grok bot)

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 = 30

If the Grok CLI supports it:

grok mcp add apple-design -- node /ABS/PATH/apple-design-mcp/dist/cli.js mcp

Grok 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.

What agents get

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.

CLI

hig toc
hig list Foundations
hig get color
hig get buttons --json
hig search "touch targets" --platform ios
hig sync
hig cache
hig mcp

Library

import { 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);

Develop

npm install
npm test
npm run build

License

MIT 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.