🍎 Apple HIG MCP Server


A high-performance Model Context Protocol server that provides instant access to Apple's Human Interface Guidelines with comprehensive design system coverage.

Perfect for developers using AI-assisted development who want fast, reliable access to Apple's design guidelines while building iOS, macOS, watchOS, tvOS, and visionOS applications.

📖 Table of Contents

- ✨ Features
- 🚀 Quick Start
- 🔧 Platform Setup
- Claude Desktop
- Claude Code
- Cursor IDE
- Windsurf IDE
- VS Code (Preview)
- Configuration Notes
- 🔧 Development Setup
- 📖 Usage Examples
- MCP Resources
- MCP Tools
- 🎨 Current Apple Design System
- 🤝 Contributing
- ⚖️ Legal & Attribution
- 🧪 Testing
- 📦 API Reference
- 🐛 Troubleshooting
- 🙏 Acknowledgments

✨ Features

- ⚡ Ultra-Fast: Instant responses via pre-generated static content (no scraping delays)
- 🔍 Smart Search: Advanced search with pre-built indices for sub-second results
- 📱 Multi-Platform: Comprehensive coverage of all Apple platforms (iOS, macOS, watchOS, tvOS, visionOS)
- 🎨 Current Design System: Always up-to-date with Apple's latest design language
- 🔄 Auto-Updated: Content refreshed every 4 months via GitHub Actions
- 🛡️ Highly Reliable: 99.9% uptime with intelligent fallback to live scraping
- 🤖 AI-Optimized: Clean markdown format optimized for AI consumption
- 📊 Scalable: Handles unlimited concurrent users with consistent performance
- 🙏 Respectful: Follows fair use principles with proper Apple attribution

🚀 Quick Start

$3

``bash
npm install -g apple-hig-mcp
`

🔧 Platform-Specific Setup

$3

Add to your Claude Desktop configuration file (claude_desktop_config.json):

macOS/Linux:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["/usr/local/lib/node_modules/apple-hig-mcp/dist/server.js"]
}
}
}
`

Windows:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\node_modules\\apple-hig-mcp\\dist\\server.js"]
}
}
}
`

$3

#### Method 1: Command Line (Recommended)
`bash


For local project scope

claude mcp add "Apple HIG" node /usr/local/lib/node_modules/apple-hig-mcp/dist/server.js

For user-wide scope (available in all projects)

claude mcp add -s user "Apple HIG" node /usr/local/lib/node_modules/apple-hig-mcp/dist/server.js
`

#### Method 2: Project Configuration File
Create .mcp.json in your project root:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["/usr/local/lib/node_modules/apple-hig-mcp/dist/server.js"]
}
}
}
`

#### Method 3: NPX (Alternative)
`bash
claude mcp add "Apple HIG" npx -- -y apple-hig-mcp
`

$3

Create .cursor/mcp.json in your project root, or go to the Cursor settings where you have MCP integrations

macOS/Linux:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["/usr/local/lib/node_modules/apple-hig-mcp/dist/server.js"]
}
}
}
`

Windows:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\node_modules\\apple-hig-mcp\\dist\\server.js"]
}
}
}
`

Find your exact path with:
`bash
npm list -g apple-hig-mcp
`

$3

#### Setup Steps
1. Open Windsurf
2. Go to Settings → Advanced → Cascade → Model Context Protocol
3. Enable MCP
4. Click the Hammer Icon in the Cascade toolbar
5. Click Configure to open the MCP configuration file

#### Configuration
macOS/Linux:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["/usr/local/lib/node_modules/apple-hig-mcp/dist/server.js"]
}
}
}
`

Windows:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\node_modules\\apple-hig-mcp\\dist\\server.js"]
}
}
}
`

$3

#### Prerequisites
- GitHub Copilot extension installed
- Agent mode enabled (chat.agent.enabled: true)

#### Configuration
Create .vscode/mcp.json in your workspace:

macOS/Linux:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["/usr/local/lib/node_modules/apple-hig-mcp/dist/server.js"]
}
}
}
`

Windows:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\node_modules\\apple-hig-mcp\\dist\\server.js"]
}
}
}
`

#### Manage Servers
- Run MCP: List Servers to view status
- Use MCP: Start/Stop/Restart commands as needed

$3

#### Why Not NPX?
We recommend using the direct file path approach instead of npx for this MCP server because:
- Optimized Dependencies: This server uses efficient keyword-based search without heavy ML dependencies
- Performance: Direct file path execution is faster and more reliable
- Consistency: Avoids potential version conflicts and download delays
- Enterprise Networks: Direct paths work better with corporate firewalls and proxy configurations

If you prefer using npx, it's still supported but may experience longer startup times.

#### Environment Variables (Optional)
For development or debugging, add environment variables:
`json
{
"mcpServers": {
"Apple HIG": {
"command": "node",
"args": ["/usr/local/lib/node_modules/apple-hig-mcp/dist/server.js"],
"env": {
"NODE_ENV": "development",
"SEARCH_CONFIG": "keyword-optimized"
}
}
}
}
`

#### Configuration File Locations
- Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %AppData%\Claude\claude_desktop_config.json
- Cursor: .cursor/mcp.json in project root
- Windsurf: Accessible via Cascade settings
- VS Code: .vscode/mcp.json in workspace
- Claude Code: Accessible via /settings command

$3

Test the server interactively:

`bash
npx @modelcontextprotocol/inspector apple-hig-mcp
`

🔧 Development Setup

$3

- Node.js 18.0.0 or higher
- npm or yarn

📖 Usage Examples

$3

#### Platform Guidelines
`
hig://ios - Complete iOS Human Interface Guidelines
hig://macos - Complete macOS Human Interface Guidelines
hig://watchos - Complete watchOS Human Interface Guidelines
hig://tvos - Complete tvOS Human Interface Guidelines
hig://visionos - Complete visionOS Human Interface Guidelines
hig://universal - Cross-platform design principles
`

#### Popular Topics (Cross-Platform)
`
hig://buttons - Button design guidelines
hig://accessibility - Accessibility requirements
hig://color - Color usage principles
hig://typography - Typography guidelines
hig://layout - Layout and spacing
hig://materials - Materials including Liquid Glass
hig://navigation-and-search - Navigation patterns
`

#### Platform-Specific Resources
`
hig://ios/foundations - iOS design foundations
hig://ios/visual-design - iOS visual design elements
hig://ios/navigation - iOS navigation patterns
`

#### Special Resources
`
hig://updates/latest - Latest HIG updates and changes
`

$3

#### Search Guidelines
`json
{
"name": "search_guidelines",
"arguments": {
"query": "button design",
"platform": "iOS",
"category": "visual-design",
"limit": 10
}
}
`

#### Get Component Specifications
`json
{
"name": "get_component_spec",
"arguments": {
"componentName": "Navigation Bar",
"platform": "iOS"
}
}
`

#### Compare Across Platforms
`json
{
"name": "compare_platforms",
"arguments": {
"componentName": "Button",
"platforms": ["iOS", "macOS", "watchOS"]
}
}
`

#### Get Latest Updates
`json
{
"name": "get_latest_updates",
"arguments": {
"since": "2025-06-01",
"platform": "iOS",
"limit": 20
}
}
`

🎨 Current Apple Design System

This server includes comprehensive coverage of Apple's latest design language:

- Advanced Materials: Access guidelines for implementing modern visual elements
- Adaptive Interface: Learn how elements intelligently adapt between contexts
- Enhanced Rendering: Understand dynamic visual effects and interactions
- System-wide Implementation: Guidelines for buttons, navigation, and entire interfaces
- Developer APIs: Information about updated SwiftUI, UIKit, and AppKit support




🤝 Contributing

We welcome contributions! This project relies on community help for maintenance, especially when Apple updates their website structure.

$3

1. Scraper Fixes (Most Important): When Apple changes their website, scrapers need updates
2. New Features: Enhanced search, new platforms, better formatting
3. Bug Fixes: Performance improvements, error handling
4. Documentation: Better examples, troubleshooting guides

$3

1. Check open issues for scraper failures
2. Use the scraper issue template to report problems
3. See CONTRIBUTING.md for detailed guidelines




⚖️ Legal & Attribution

$3

This project operates under fair use principles for educational and development purposes:

- ✅ Smart wrapper around Apple's public documentation
- ✅ Proper attribution in all content responses
- ✅ Educational purpose for developers
- ✅ Respectful scraping with rate limiting

$3

All content served by this server includes proper attribution:

> This content is sourced from Apple's Human Interface Guidelines.
> © Apple Inc. All rights reserved. Provided for educational purposes.
> For official information, visit: https://developer.apple.com/design/human-interface-guidelines/

$3

This project is not affiliated with Apple Inc. and does not claim ownership of Apple's content. It provides a technical interface to publicly available documentation under fair use principles.

🧪 Testing

$3


`bash
npm test # Run test suite
npm run lint # Code linting
npm run health-check # Test scraper functionality
`

$3

`bash

Test with MCP Inspector

npx @modelcontextprotocol/inspector dist/server.js

Test specific functionality

npm run dev # Start development server
`

📦 API Reference

$3

| URI Pattern | Description |
|-------------|-------------|
| hig:// | Complete platform guidelines (ios, macos, watchos, tvos, visionos) |
| hig:/// | Category-specific guidelines |
| hig://universal | Cross-platform design principles |
| hig:// | Topic-specific guidelines (buttons, materials, etc.) |
| hig://updates/latest | Latest HIG changes and additions |

$3

| Tool | Description | Key Arguments |
|------|-------------|---------------|
| search_guidelines | Search HIG content with enhanced keyword matching | query, platform, category, limit |
| get_component_spec | Get component specifications | componentName, platform |
| get_design_tokens | Get design system values | component, platform, tokenType |
| get_accessibility_requirements | Get accessibility guidelines | component, platform` |

🐛 Troubleshooting

$3

Scraper not working?
- Check if Apple's website is accessible
- Look for recent website structure changes
- Check existing issues

Empty or incomplete content?
- Clear cache and retry
- Check network connectivity
- Report as a scraper issue

Performance issues?
- Check cache configuration
- Monitor memory usage
- Adjust request rate limiting

🙏 Acknowledgments

- Apple Inc. for creating comprehensive design guidelines
- Model Context Protocol team for the excellent framework
- Open source community for contributions and maintenance

---

Built with ❤️ for the developer community

Bringing Apple's design excellence directly to your AI-assisted development workflow.