Apple MCP（模型上下文协议）工具
一组工具，允许像 Claude 这样的 AI 助手通过模型上下文协议 (MCP) 与 Apple 应用程序和服务进行交互。
概述
该软件包提供了用于与各种 Apple 应用程序和服务交互的 MCP 工具，包括：
- 联系人：从 Apple 通讯录应用中搜索和检索联系人
- 笔记：在 Apple Notes 应用中搜索、检索、创建笔记和列出文件夹
- 信息：发送、阅读、安排信息和检查未读信息
- 邮件：阅读未读邮件、搜索邮件、发送电子邮件
- 提醒事项：在 Apple 提醒事项应用中搜索、创建和打开提醒事项
- 日历：在 Apple 日历应用中搜索、创建和打开日历事件
- 地图：搜索位置、管理指南、保存收藏夹和获取路线
- 网络搜索：使用 DuckDuckGo 搜索网络并从搜索结果中检索内容
安装
# Install with npm
npm install @sage/mcp-apple
# Install with yarn
yarn add @sage/mcp-apple
# Install with bun
bun add @sage/mcp-apple
要求
- macOS 操作系统
- Node.js 18+ 或 Bun 运行时
- 访问 Apple 应用程序（联系人、备忘录、信息、邮件等）的适当权限
用法
启动 MCP 服务器
# Using the CLI
npx apple-mcp
# Using bun
bun run dev
连接到克劳德
要将这些工具与 Claude 结合使用，您需要将 MCP 服务器连接到 Claude。您可以使用 MCP 代理或直接通过 Claude 界面（如有）进行连接。
# Example using mcp-proxy
mcp-proxy --server "bun run /path/to/apple-mcp/index.ts"
工具示例
联系方式
// Search for a contact by name
{
"operation": "contacts",
"name": "John Doe"
}
// List all contacts
{
"operation": "contacts"
}
笔记
// Search for notes containing specific text
{
"operation": "notes",
"operation": "search",
"searchText": "meeting notes"
}
// Create a new note
{
"operation": "notes",
"operation": "create",
"title": "Shopping List",
"body": "- Milk\n- Eggs\n- Bread",
"folderName": "Personal"
}
// List all notes in a folder
{
"operation": "notes",
"operation": "list",
"folderName": "Work"
}
// List all folders
{
"operation": "notes",
"operation": "listFolders"
}
// Create a new folder
{
"operation": "notes",
"operation": "createFolder",
"folderName": "Projects"
}
消息
// Send a message
{
"operation": "messages",
"operation": "send",
"phoneNumber": "+1234567890",
"message": "Hello, how are you?"
}
// Read messages from a contact
{
"operation": "messages",
"operation": "read",
"phoneNumber": "+1234567890",
"limit": 5
}
// Schedule a message
{
"operation": "messages",
"operation": "schedule",
"phoneNumber": "+1234567890",
"message": "Don't forget our meeting tomorrow!",
"scheduledTime": "2023-12-01T09:00:00Z"
}
// Check unread messages
{
"operation": "messages",
"operation": "unread"
}
邮件
// Check unread emails
{
"operation": "mail",
"operation": "unread",
"limit": 10
}
// Search emails
{
"operation": "mail",
"operation": "search",
"searchTerm": "invoice",
"limit": 5
}
// Send an email
{
"operation": "mail",
"operation": "send",
"to": "recipient@example.com",
"subject": "Meeting Agenda",
"body": "Here's the agenda for our meeting tomorrow...",
"cc": "colleague@example.com"
}
// List mailboxes
{
"operation": "mail",
"operation": "mailboxes"
}
// List accounts
{
"operation": "mail",
"operation": "accounts"
}
提醒事项
// List all reminders
{
"operation": "reminders",
"operation": "list"
}
// Search for reminders
{
"operation": "reminders",
"operation": "search",
"searchText": "groceries"
}
// Create a reminder
{
"operation": "reminders",
"operation": "create",
"name": "Buy milk",
"listName": "Shopping",
"notes": "Get organic milk",
"dueDate": "2023-12-01T18:00:00Z"
}
// Open a reminder
{
"operation": "reminders",
"operation": "open",
"searchText": "Buy milk"
}
// List reminders by list ID
{
"operation": "reminders",
"operation": "listById",
"listId": "x-apple-reminder://list/123456"
}
日历
// Search for events
{
"operation": "calendar",
"operation": "search",
"searchText": "meeting",
"fromDate": "2023-12-01T00:00:00Z",
"toDate": "2023-12-31T23:59:59Z"
}
// List upcoming events
{
"operation": "calendar",
"operation": "list",
"limit": 5
}
// Create an event
{
"operation": "calendar",
"operation": "create",
"title": "Team Meeting",
"startDate": "2023-12-05T14:00:00Z",
"endDate": "2023-12-05T15:00:00Z",
"location": "Conference Room A",
"notes": "Quarterly review meeting",
"isAllDay": false,
"calendarName": "Work"
}
// Open an event
{
"operation": "calendar",
"operation": "open",
"eventId": "x-apple-calendar://event/123456"
}
地图
// Search for locations
{
"operation": "maps",
"operation": "search",
"query": "coffee shops near me",
"limit": 5
}
// Save a location
{
"operation": "maps",
"operation": "save",
"name": "Favorite Coffee Shop",
"address": "123 Main St, Anytown, USA"
}
// Get directions
{
"operation": "maps",
"operation": "directions",
"fromAddress": "123 Main St, Anytown, USA",
"toAddress": "456 Oak Ave, Anytown, USA",
"transportType": "driving"
}
// Drop a pin
{
"operation": "maps",
"operation": "pin",
"name": "Meeting Point",
"address": "Central Park, New York, NY"
}
// List guides
{
"operation": "maps",
"operation": "listGuides"
}
// Create a guide
{
"operation": "maps",
"operation": "createGuide",
"guideName": "Favorite Restaurants"
}
// Add to guide
{
"operation": "maps",
"operation": "addToGuide",
"guideName": "Favorite Restaurants",
"address": "789 Pine St, Anytown, USA"
}
// Get map center coordinates
{
"operation": "maps",
"operation": "getCenter"
}
// Set map center coordinates
{
"operation": "maps",
"operation": "setCenter",
"latitude": 37.7749,
"longitude": -122.4194
}
网页搜索
// Search the web
{
"operation": "webSearch",
"query": "how to make chocolate chip cookies"
}
建筑学
Apple MCP 工具采用模块化架构构建：
- index.ts ：设置 MCP 服务器并注册工具的主入口点
- tools.ts ：定义工具模式和描述
- src/handlers/ ：包含每个工具的处理函数
- src/scripts/ ：包含用于与 Apple 应用程序交互的 AppleScript 脚本
- utils/ ：包含每个 Apple 服务的实用程序模块
该工具使用延迟加载来提高性能，仅在需要时加载模块。
安全和权限
此工具需要访问各种 Apple 应用程序和服务。您需要在 macOS 提示时授予权限。您可以在“系统偏好设置”>“安全和隐私”>“隐私”中管理这些权限。
发展
设置
# Clone the repository
git clone https://github.com/yourusername/apple-mcp.git
cd apple-mcp
# Install dependencies
bun install
以开发模式运行
代码风格
- 使用两个空格缩进
- 保持行数不超过 100 个字符
- 对函数参数和返回使用显式类型注释
- 类型、接口和工具常量遵循 PascalCase
- 对变量和函数使用驼峰命名法
贡献
欢迎贡献代码！欢迎提交 Pull 请求。
- 分叉存储库
- 创建你的功能分支（
git checkout -b feature/amazing-feature ） - 提交您的更改（
git commit -m 'Add some amazing feature' ） - 推送到分支（
git push origin feature/amazing-feature ） - 打开拉取请求