apple-fm-mcp

apple-fm-mcp

  

MCP server for Apple on-device Foundation Models. Use Apple Intelligence from any MCP client — Claude Code, Cursor, Windsurf — running locally on your Mac for free.

Built on python-apple-fm-sdk and the Model Context Protocol.

Requirements

• macOS 26+ (Tahoe) with Apple Intelligence enabled
• Apple Silicon Mac (M1+)
• Python 3.10+
• apple-fm-sdk — Apple's Python SDK for on-device Foundation Models

Installation

From source (recommended)

git clone https://github.com/yihan2099/apple-fm-mcp.git
cd apple-fm-mcp
uv sync

You also need the Apple Foundation Models SDK:

pip install git+https://github.com/apple/python-apple-fm-sdk.git

Note: apple-fm-mcp is not yet published to PyPI. uv tool install and pip install from PyPI will be available in a future release.

Usage

Claude Code

claude mcp add apple-fm -- apple-fm-mcp

Cursor / Windsurf

Add to your MCP config (~/.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "apple-fm": {
      "command": "apple-fm-mcp"
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector apple-fm-mcp

Tools

| Tool | Description | |------|-------------| | check_model_availability | Check if the on-device model is available | | generate | One-shot text generation with optional instructions | | generate_structured | JSON output matching a provided schema | | chat | Multi-turn conversation with named sessions | | tag_content | Content tagging using Apple's CONTENT_TAGGING use case | | list_sessions | List active conversation sessions | | clear_session | Delete a named session | | clear_all_sessions | Delete all sessions |

Examples

Generate text: > "Use apple-fm to explain what a closure is in Swift"

Structured output: > "Use apple-fm generate_structured to extract {name, email, company} from this text: ..."

Multi-turn chat: > "Start an apple-fm chat session called 'code-review' and ask it to review this function" > "In the 'code-review' session, ask it to suggest improvements"

Resources

| URI | Description | |-----|-------------| | apple-fm://status | Model availability + device info | | apple-fm://sessions | Active sessions metadata | | apple-fm://transcript/{name} | Conversation transcript for a session |

Prompt Templates

| Prompt | Parameters | Description | |--------|-----------|-------------| | summarize | text, style (concise/detailed/bullet-points) | Summarize text | | extract_structured | text, fields (comma-separated) | Extract named fields as JSON | | classify | text, categories (comma-separated) | Single-label classification |

Limitations

• macOS only — Apple Foundation Models require Apple Silicon and macOS 26+
• No streaming — MCP tools return complete responses
• In-memory sessions — conversation state is lost when the server restarts
• On-device model limits — the model is optimized for short tasks (summarization, extraction, classification), not long-form generation
• No image/audio — text-only; multimodal support may come in future SDK versions

SDK Documentation

This project wraps apple-fm-sdk. Key references:

• Official SDK docs — getting started, guides, full API reference
• Local API reference — curated extract of the classes and enums used by this MCP server

Development

git clone https://github.com/yihan2099/apple-fm-mcp.git
cd apple-fm-mcp
uv sync --dev
uv run pytest

Tests mock apple_fm_sdk so they run on any platform.

Linting

uv run ruff check src/ tests/
uv run ruff format src/ tests/

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT