Python Apple MCP

Python苹果MCP（模型上下文协议）

服务器的Python实现，使用FastMCP处理与macOS应用程序（如联系人、笔记、邮件、消息、提醒、日历和地图）的交互。

特性

• 通过AppleScript与macOS原生应用程序交互
• 异步操作以获得更好的性能
• 全面的错误处理
• 使用Pydantic模型的类型安全接口
• 广泛的测试覆盖范围
• 模块化设计，易于扩展

支持的应用程序

• 联系人
• 备注
• 邮件
• 消息
• 提醒事项
• 日历
• 地图

安装

1. 克隆存储库：

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

1. 创建虚拟环境：

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项：

pip install -r requirements.txt

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

pip install -r requirements-test.txt

用法

基础示例

from apple_mcp import FastMCP, Context

# Initialize FastMCP server
mcp = FastMCP("Apple MCP")

# Use the tools
@mcp.tool()
def find_contact(name: str) -> List[Contact]:
    """Search for contacts by name"""
    # Implementation here
    pass

# Run the server
if __name__ == "__main__":
    mcp.run()

使用单个模块

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

# Initialize modules
contacts = ContactsModule()
notes = NotesModule()

# Use the modules
async def main():
    # Find a contact
    contact = await contacts.find_contact("John")
    
    # Create a note
    await notes.create_note(
        title="Meeting Notes",
        body="Discussion points...",
        folder_name="Work"
    )

# Run the async code
import asyncio
asyncio.run(main())

测试

运行测试套件：

pytest

运行覆盖率测试：

pytest --cov=utils tests/

运行特定测试文件：

pytest tests/test_contacts.py

API文档

联系人模块

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

备注模块

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

邮件模块

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

消息模块

• send_message(to: str, content: str) -> bool：发送iMessage
• read_messages(phone_number: str) -> List[Message]：阅读消息
• schedule_message(to: str, content: str, scheduled_time: str) -> Dict：安排一条消息

提醒模块

• create_reminder(name: str, list_name: str, notes: str, due_date: str) -> Dict：创建提醒
• search_reminders(query: str) -> List[Dict]：搜索提醒
• get_all_reminders() -> List[Dict]：获取所有提醒

日历模块

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

地图模块

• search_locations(query: str) -> List[Location]：搜索地点
• get_directions(from_address: str, to_address: str, transport_type: str) -> str：获取路线
• save_location(name: str, address: str) -> Dict：将位置保存到收藏夹

贡献

1. 分叉存储库
2. 创建要素分支
3. 提交您的更改
4. 推到分支
5. 创建拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。