Python Apple MCP (模型上下文协议)

一个使用 FastMCP 处理 macOS 应用（如 Contacts、Notes、Mail、Messages、Reminders、Calendar 和 Maps）的 Python 服务器实现。

特性

• 使用 Apple 脚本与 macOS 原生应用交互
• 异步操作以提升性能
• 全面错误处理
• 类型安全接口，使用 Pydantic 模型
• 丰富的测试覆盖率
• 模块化设计，便于扩展

支持的应用程序

• Contacts（联系人）
• Notes（笔记）
• Mail（邮件）
• Messages（信息）
• Reminders（提醒事项）
• Calendar（日历）
• Maps（地图）

安装

1. 克隆仓库：

git clone https://github.com/jxnl/python-apple-mcp.git
cd python-apple-mcp

2. 创建虚拟环境：

python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

3. 安装依赖项：

pip install -r requirements.txt

4. 安装测试依赖（可选）：

pip install -r requirements-test.txt

使用方法

基本示例

from apple_mcp import FastMCP, Context

# 初始化 FastMCP 服务器
mcp = FastMCP("Apple MCP")

# 使用工具
@mcp.tool()
def find_contact(name: str) -> List[Contact]:
    """按名称搜索联系人"""
    # 实现代码在此处
    pass

# 运行服务器
if __name__ == "__main__":
    mcp.run()

单独使用模块

from utils.contacts import ContactsModule
from utils.notes import NotesModule

# 初始化模块
contacts = ContactsModule()
notes = NotesModule()

# 使用模块
async def main():
    # 查找联系人
    contact = await contacts.find_contact("John")
    
    # 创建笔记
    await notes.create_note(
        title="会议记录",
        body="讨论要点...",
        folder_name="工作"
    )

# 运行异步代码
import asyncio
asyncio.run(main())

测试

运行测试套件：

pytest

使用覆盖运行测试：

pytest --cov=utils tests/

运行特定测试文件：

pytest tests/test_contacts.py

API 文档

Contacts 模块（联系人）

• find_contact(name: str) -> List[Contact]：按名称搜索联系人
• get_all_contacts() -> List[Contact]：获取所有联系人
• create_contact(name: str, phones: List[str]) -> Contact：创建新联系人

Notes 模块（笔记）

• find_note(query: str) -> List[Note]：搜索笔记
• create_note(title: str, body: str, folder_name: str) -> Note：创建新笔记
• get_all_notes() -> List[Note]：获取所有笔记

Mail 模块（邮件）

• send_email(to: str, subject: str, body: str) -> str：发送电子邮件
• search_emails(query: str) -> List[Email]：搜索邮件
• get_all_emails() -> List[Email]：获取所有邮件

Messages 模块（信息）

• send_message(to: str, text: str) -> Message：发送消息
• search_messages(query: str) -> List[Message]：搜索消息
• get_all_messages() -> List[Message]：获取所有消息

Reminders 模块（提醒事项）

• create_reminder(title: str, due_date: datetime) -> Reminder：创建提醒
• search_reminders(query: str) -> List[Reminder]：搜索提醒
• get_all_reminders() -> List[Reminder]：获取所有提醒

Calendar 模块（日历）

• create_event(title: str, start_date: datetime, end_date: datetime) -> Event：创建事件
• search_events(query: str) -> List[Event]：搜索事件
• get_all_events() -> List[Event]：获取所有事件

Maps 模块（地图）

• get_directions(start: Location, end: Location) -> Directions：获取路线
• search_places(name: str) -> List[Place]：搜索地点
• get_map_image(bounds: Bounds) -> bytes：获取地图图像

贡献指南

欢迎贡献！请参考项目仓库中的 CONTRIBUTING.md 文件。

许可证

此项目受 MIT License 保护。