🚀 Python Apple MCP (模型上下文协议)
Python Apple MCP 是一个使用 FastMCP 处理 macOS 应用（如 Contacts、Notes、Mail、Messages、Reminders、Calendar 和 Maps）的 Python 服务器实现，可与 macOS 原生应用高效交互。
🚀 快速开始
Python Apple MCP 借助 Apple 脚本与 macOS 原生应用交互，为开发者提供了便捷的方式来操作这些应用。下面将详细介绍如何快速上手。
✨ 主要特性
- 原生交互：使用 Apple 脚本与 macOS 原生应用交互，无缝对接系统功能。
- 性能优化：采用异步操作以提升性能，确保高效处理任务。
- 错误处理：具备全面错误处理机制，保障程序稳定运行。
- 类型安全：提供类型安全接口，使用 Pydantic 模型，增强代码可靠性。
- 测试完备：拥有丰富的测试覆盖率，保证代码质量。
- 易于扩展：模块化设计，便于开发者根据需求进行扩展。
📦 安装指南
按照以下步骤完成项目的安装：
- 克隆仓库：
git clone https://github.com/jxnl/python-apple-mcp.git
cd python-apple-mcp
- 创建虚拟环境：
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
- 安装依赖项：
pip install -r requirements.txt
- 安装测试依赖（可选）：
pip install -r requirements-test.txt
💻 使用示例
基础用法
from apple_mcp import FastMCP, Context
from typing import List
from models.contact import Contact
# 初始化 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
import asyncio
# 初始化模块
contacts = ContactsModule()
notes = NotesModule()
# 使用模块
async def main():
# 查找联系人
contact = await contacts.find_contact("John")
# 创建笔记
await notes.create_note(
title="会议记录",
body="讨论要点...",
folder_name="工作"
)
# 运行异步代码
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 保护。