{
"mcpServers": {
"tasknote-bridge": {
"command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
}
}
}
{
"mcpServers": [
{
"name": "tasknote-bridge",
"command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
"args": []
}
]
}
{
"mcpServers": {
"tasknote-bridge": {
"command": "nc",
"args": ["localhost", "8000"]
}
}
}
🚀 TaskNote Bridge - Swift MCP Server 与 Things 3 和 Apple Notes 的集成 ✅
TaskNote Bridge 是一款原生 macOS Swift 应用程序,它实现了一个完整的 模型上下文协议 (MCP) 服务器,用于集成 Things 3 和 Apple Notes。借助该应用,你可以通过 AI 助手便捷地创建任务和笔记。
🚀 快速开始
📥 下载与安装
- 下载最新版本
- 打开 DMG 文件,将 TaskNote Bridge 拖移到“应用程序”文件夹
- 启动应用程序 - MCP 服务器将自动启动
- 使用以下设置配置 VS Code
⚙️ Claude Desktop 配置
将以下内容添加到你的 Claude Desktop MCP 服务器配置中:
{
"mcpServers": {
"tasknote-bridge": {
"command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
}
}
}
⚠️ 重要提示
请将
/path/to/tasknote-bridge/
替换为你实际的安装目录。例如:
- 如果你下载的是发布版本:
/Users/[用户名]/Downloads/tasknote-bridge/
- 如果你克隆了仓库:
/Users/[用户名]/Projects/tasknote-bridge/
- 如果你将其移到了“应用程序”文件夹:
/Applications/TaskNote Bridge/
⚙️ VS Code 配置
将以下内容添加到你的 VS Code settings.json
文件中:
{
"mcp": {
"inputs": [],
"servers": {
"things-swift": {
"command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh",
"args": []
}
}
}
}
🎉 完成以上步骤后,你就可以通过 AI 助手创建任务和笔记了!
✨ 主要特性
原生 macOS MCP 服务器应用程序
- 完整的 MCP 服务器:使用 Swift 完整实现 MCP 协议,集成 Things 3 和 Apple Notes 工具
- 实时监控:具备服务器状态仪表盘,可实时跟踪活动
- TCP 传输:基于网络的传输协议,与通用 MCP 客户端兼容
- 日志流:实时服务器日志,支持过滤和搜索功能
- 连接管理:监控活动客户端连接以及请求/响应活动
- SwiftUI 界面:现代 macOS 界面,用于服务器监控和控制
Things 3 集成
- 访问所有主要的 Things 列表(收件箱、今日、即将到来等)
- 项目和区域管理
- 标签操作
- 高级搜索功能
- 跟踪最近的项目
- 详细的项目信息,包括清单
- 支持嵌套数据(区域内的项目、项目内的待办事项)
- 直接在 Things 3 应用程序中打开特定任务
Apple Notes 集成
- 创建带有标题、内容和标签的新笔记
- 按标题搜索笔记
- 检索笔记内容
- 列出所有笔记
- 直接在 Apple Notes 应用程序中打开笔记
- 删除笔记
- 完整的 AppleScript 集成,实现无缝的 macOS 体验
📦 安装指南
选项 1:下载应用程序(推荐)
从 发布页面 下载最新的 TaskNote Bridge.app
。
选项 2:从源代码构建
如果你想从源代码构建,你需要:
- Xcode 14.0 或更高版本
- macOS 13.0 或更高版本
克隆仓库并进行构建:
# 克隆仓库
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp
# 在 Xcode 中打开并构建
open "TaskNote Bridge.xcodeproj"
配置
前提条件
- 任何兼容 MCP 的 AI 助手或工具(Claude Desktop、带有 MCP 扩展的 VS Code、Cursor、Continue、Zed 等)
- Things 3(必须在“设置” -> “通用”中开启“启用 Things URL”)
- Apple Notes(内置于 macOS)
- VS Code(带有 MCP 扩展)
💻 使用示例
基础用法
# 测试 stdio 服务器(在 Things 3 中创建任务!)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Hello from VS Code!", "tags": ["test"]}}}' | ./launch_swift_mcp_stdio.sh
# 预期输出:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ Task 'Hello from VS Code!' created in Things 3","type":"text"}],"isError":false}}
# ✅ 检查 Things 3 - 你的任务将出现在那里!
高级用法
GUI 监控
# 构建并运行 macOS 应用程序
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# 服务器将自动启动并带有监控界面
📚 详细文档
项目架构
本项目提供了 两种 MCP 服务器实现,以满足不同的使用场景:
📱 TaskNote Bridge.app(GUI 应用程序)
- 用途:具有可视化监控界面的 macOS 应用程序
- 传输方式:TCP 服务器(端口 8000),用于基于网络的连接
- 特性:实时仪表盘、连接监控、日志查看器
- 使用场景:当你需要可视化监控服务器活动时
- 启动方式:从“应用程序”文件夹中打开应用程序
📟 swift_mcp_stdio.swift(命令行服务器)
- 用途:轻量级基于 stdio 的 MCP 服务器
- 传输方式:标准输入/输出通信
- 特性:直接处理 JSON-RPC 消息,开销最小
- 使用场景:推荐用于 Claude Desktop 和大多数 MCP 客户端
- 启动方式:通过
launch_swift_mcp_stdio.sh
脚本
🔧 如何选择?
MCP 客户端 | 推荐的服务器 | 配置 |
---|---|---|
Claude Desktop | ✅ stdio 脚本 | command: "/path/to/launch_swift_mcp_stdio.sh" |
VS Code MCP | ✅ stdio 脚本 | 与 Claude Desktop 相同 |
自定义 TCP 客户端 | 📱 GUI 应用程序 | 连接到 localhost:8000 |
开发/测试 | 📱 GUI 应用程序 | 可视化监控 + TCP 访问 |
💡 使用建议
大多数 MCP 客户端(包括 Claude Desktop)期望基于 stdio 的通信,而不是 TCP 连接。
MCP 客户端连接指南
TaskNote Bridge 支持多种连接方法,以与各种 MCP 客户端配合使用。选择最适合你客户端的方法:
🎯 Claude Desktop
配置 Claude Desktop 以使用基于 stdio 的 MCP 服务器:
- 打开 Claude Desktop
- 点击左下角的设置齿轮(⚙️)
- 选择“开发者”
- 在“MCP 服务器”部分,点击“编辑配置”
- 添加以下配置:
{
"mcpServers": {
"tasknote-bridge": {
"command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
}
}
}
⚠️ 重要提示
请将
/path/to/tasknote-bridge/
替换为你实际的安装目录。常见路径如下:
- 下载的发布版本:
/Users/[用户名]/Downloads/tasknote-bridge/launch_swift_mcp_stdio.sh
- 克隆的仓库:
/Users/[用户名]/Projects/tasknote-bridge/launch_swift_mcp_stdio.sh
- 应用程序包安装:
/Applications/TaskNote Bridge.app/Contents/Resources/launch_swift_mcp_stdio.sh
- 保存配置
- 重启 Claude Desktop 以应用更改
✅ 成功提示:Claude Desktop 现在将通过 stdio 传输进行连接,这是 MCP 通信推荐且最可靠的方法。
🔧 VS Code 与 MCP 扩展
- 为 VS Code 安装 MCP 扩展:
- 打开 VS Code 扩展(Cmd + Shift + X)
- 搜索“Model Context Protocol”并安装
- 配置 VS Code 设置 (
settings.json
):
{
"mcp": {
"servers": {
"tasknote-bridge": {
"command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
"args": []
}
}
}
}
- 重启 VS Code 以加载 MCP 服务器
🖱️ Cursor IDE
- 打开 Cursor 设置(Cmd + ,)
- 导航到扩展 → 模型上下文协议
- 添加服务器配置:
{
"command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
"args": []
}
⚡ Continue(VS Code 扩展)
- 在 VS Code 中安装 Continue 扩展
- 打开 Continue 配置(通常为
~/.continue/config.json
) - 添加 MCP 服务器:
{
"mcpServers": [
{
"name": "tasknote-bridge",
"command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
"args": []
}
]
}
🚀 Zed 编辑器
- 打开 Zed 设置(Cmd + ,)
- 添加到你的 settings.json:
{
"assistant": {
"mcp_servers": {
"tasknote-bridge": {
"command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh"
}
}
}
}
🛠️ 自定义 MCP 客户端
对于任何自定义 MCP 客户端或应用程序:
TCP 连接
- 主机:
localhost
- 端口:
8000
(默认,可在 TaskNote Bridge 应用程序中配置) - 协议:带有 JSON-RPC 2.0 的 TCP
Stdio 连接
- 命令:
/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
- 传输方式:带有 JSON-RPC 2.0 的标准输入/输出
📋 验证步骤
配置任何客户端后:
- 测试连接:
# 进行 stdio 测试
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
# 进行 TCP 测试(如果服务器正在运行)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc localhost 8000
- 检查可用工具 - 你应该会看到如下工具:
bb7_add-todo
bb7_add-project
bb7_get-today
bb7_notes-create
- 还有更多...
- 测试任务创建:
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Test from MCP!", "tags": ["test"]}}}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
- 在 Things 3 中验证 - 测试任务应出现在你的收件箱中
🔍 解决连接问题
Claude Desktop 无法连接
- 检查配置文件是否为有效的 JSON
- 验证文件路径是否存在:
/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
- 完全重启 Claude Desktop
- 检查 Claude 日志:
~/Library/Logs/Claude/mcp*.log
TCP 连接问题
- 确保 TaskNote Bridge 应用程序正在运行
- 检查端口 8000 是否可用:
lsof -i :8000
- 在 TaskNote Bridge 设置中尝试不同的端口
- 验证防火墙设置是否允许本地连接
Stdio 连接问题
- 验证脚本权限:
ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
- 在终端中直接测试脚本
- 确保在 Things 3 → 设置 → 通用中启用了 Things 3 URL
使用方法
在 TaskNote Bridge 应用程序中
- 从“应用程序”文件夹中启动 TaskNote Bridge 应用程序。
- 该应用程序提供了一个原生 macOS 界面,用于:
- 查看你的 Things 3 任务、项目和区域
- 管理你的 Apple 笔记
- 监控 MCP 服务器连接
- 实时查看活动日志
在 Claude Desktop 中
连接成功后,你可以使用自然语言与 TaskNote Bridge 进行交互: Things 3 示例:
- “我今天的待办事项清单上有什么?”
- “创建一个待办事项,为我下周的海滩度假打包”
- “为阵亡将士纪念日烧烤创建一个项目,并包含规划任务”
- “显示我所有与工作相关的任务”
- “将购物任务标记为已完成”
- “添加一个明天给妈妈打电话的任务”
Apple Notes 示例:
- “创建一个包含今天站立会议会议记录的笔记”
- “在我的笔记中搜索有关季度审查的任何内容”
- “记录我想尝试的新餐厅”
- “显示我所有包含旅行信息的笔记”
在 VS Code 中
安装并配置 MCP 扩展后:
- 打开命令面板(Cmd + Shift + P)
- 输入“MCP”以查看可用的 MCP 命令
- 使用“MCP: 调用工具”与 Things 工具进行交互
- 或者使用任何支持 MCP 的 AI 助手访问你的 Things 数据
对于任何兼容 MCP 的工具
此服务器遵循标准 MCP 协议,可以与任何兼容 MCP 的应用程序或 AI 助手配合使用。只需使用上述方法之一将你的工具配置为连接到 Swift MCP 服务器。
兼容的应用程序包括:
- Claude Desktop
- 带有 MCP 扩展的 VS Code
- Cursor
- Continue
- Zed
- Sourcegraph Cody
- 任何自定义 MCP 客户端实现
💡 更好集成的专业提示
Claude Desktop 优化
- 在 Claude 中创建一个自定义项目,包含你使用 Things 3 的方式以及如何组织区域、项目、标签等的说明。
- 告知 Claude 在创建任务时应包含哪些信息(例如,任务描述中的相关详细信息)
- 与日历 MCP 服务器结合使用,让 Claude 为任务安排时间并从日历事件中创建待办事项。
多客户端使用
- 使用 TCP 模式 同时连接多个客户端
- 保持 TaskNote Bridge 应用程序打开,以实时监控所有 MCP 活动
- 查看应用程序日志,如果你在工具调用时遇到任何问题
高级工作流程
- “使用艾森豪威尔矩阵评估我当前的待办事项”
- “帮助我使用 Things 进行 GTD 式的每周回顾”
- “为 [项目名称] 创建一个包含子任务和截止日期的项目计划”
- “分析我的任务完成模式并提出改进建议”
🔧 技术细节
项目结构
TaskNote Bridge.app/ # macOS Swift 应用程序
├── Contents/
│ ├── MacOS/ # 包含 MCP 服务器的原生 Swift 可执行文件
│ │ └── TaskNote Bridge # 带有嵌入式 MCP 服务器的主应用程序
│ ├── Resources/ # 应用程序资源
│ └── Info.plist # 应用程序包配置
├── TaskNote Bridge.xcodeproj/ # Xcode 项目
├── SwiftMCPServer.swift # 核心 MCP 服务器实现
├── ThingsIntegration.swift # Things 3 集成层
├── NotesIntegration.swift # Apple Notes 集成层
└── README.md # 本文档
可用工具
列表视图
get-inbox
- 获取收件箱中的待办事项get-today
- 获取今天到期的待办事项get-upcoming
- 获取即将到来的待办事项get-anytime
- 获取任何时间的待办事项列表get-someday
- 获取未来某天的待办事项列表get-logbook
- 获取已完成的待办事项get-trash
- 获取已删除的待办事项
基本操作
get-todos
- 获取待办事项,可选择按项目过滤get-projects
- 获取所有项目get-areas
- 获取所有区域
标签操作
get-tags
- 获取所有标签get-tagged-items
- 获取带有特定标签的项目
搜索操作
search-todos
- 按标题/笔记进行简单搜索search-advanced
- 带有多个过滤器的高级搜索open-todo
- 按标题搜索待办事项并在 Things 应用程序中打开
基于时间的操作
get-recent
- 获取最近创建的项目
工具参数
get-todos
project_uuid
(可选) - 按项目过滤待办事项include_items
(可选,默认值:true) - 包含清单项目
get-projects / get-areas / get-tags
include_items
(可选,默认值:false) - 包含包含的项目
search-advanced
status
- 按状态过滤(未完成/已完成/已取消)start_date
- 按开始日期过滤(YYYY-MM-DD)deadline
- 按截止日期过滤(YYYY-MM-DD)tag
- 按标签过滤area
- 按区域 UUID 过滤type
- 按项目类型过滤(待办事项/项目/标题)
get-recent
period
- 时间段(例如,'3d'、'1w'、'2m'、'1y')
open-todo
title
- 要搜索并打开的待办事项的标题或部分标题
notes-open
title
- 要在 Apple Notes 中打开的笔记的准确标题
🔍 故障排除
连接问题
Claude Desktop
- 检查配置文件:确保 JSON 配置有效且格式正确
- 验证文件路径:确保
/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
存在 - 重启 Claude:在更改配置后,完全退出并重新启动 Claude Desktop
- 检查日志:查看
~/Library/Logs/Claude/mcp*.log
中的 Claude 日志
TCP 连接问题
- 应用程序运行:确保 TaskNote Bridge 应用程序正在运行,并且 TCP 服务器已启动
- 端口可用性:使用
lsof -i :8000
检查端口 8000 是否可用 - 防火墙设置:验证 macOS 防火墙是否允许本地连接
- 尝试不同的端口:如有需要,在 TaskNote Bridge 应用程序设置中更改端口
Stdio 连接问题
- 脚本权限:验证脚本是否可执行:
ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
- 直接测试:在终端中测试脚本,确保其正常工作
- Things 3 URL:确保在 Things 3 → 设置 → 通用中启用了“启用 Things URL”
工具执行问题
服务器包含全面的错误处理,用于处理以下情况:
- 无效的 UUID 和格式错误的请求
- 缺少必需的参数
- Things 3 数据库访问错误
- Apple Notes AppleScript 执行错误
- 数据格式化和序列化错误
所有错误都会记录详细的描述性消息。要查看 MCP 日志:
# 实时跟踪 Claude Desktop 日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# 检查 TaskNote Bridge 应用程序日志
# 打开 TaskNote Bridge 应用程序并查看内置的日志查看器
# 直接测试服务器
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
常见错误解决方案
“权限被拒绝”错误
- 运行:
chmod +x /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
- 在“系统偏好设置” → “安全性与隐私”中授予 TaskNote Bridge 应用程序必要的权限
“Things 3 无响应”错误
- 确保已安装 Things 3 并至少启动过一次
- 检查 Things 3 设置中是否启用了“启用 Things URL”
- 尝试重启 Things 3
“Apple Notes 访问被拒绝”错误
- 在“系统偏好设置” → “安全性与隐私” → “自动化”中授予 TaskNote Bridge 控制 Apple Notes 的权限
- 确保 Apple Notes 应用程序未受到任何安全软件的限制
Claude Desktop 连接问题
“请求超时”/服务器无响应
如果 Claude Desktop 显示超时错误或未收到响应: ❌ 错误配置(导致超时):
{
"mcpServers": {
"tasknote-bridge": {
"command": "nc",
"args": ["localhost", "8000"]
}
}
}
✅ 正确配置:
{
"mcpServers": {
"tasknote-bridge": {
"command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
}
}
}
原因:
- Claude Desktop 期望 基于 stdio 的通信(启动子进程)
nc localhost 8000
方法尝试通过 netcat 使用 TCP,无法正确处理 MCP 协议初始化- stdio 脚本提供了 Claude Desktop 所需的正确 JSON-RPC 消息处理
解决方法:
- 更新你的 Claude Desktop 配置,使用 stdio 脚本
- 重启 Claude Desktop
- 现在连接应该不会出现超时问题
验证服务器是否正常工作
直接测试 stdio 服务器:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | /path/to/tasknote-bridge/launch_swift_mcp_stdio.sh
你应该会立即看到如下响应:
{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"things-mcp-swift","version":"1.0.0"},"protocolVersion":"2024-11-05","capabilities":{"tools":{}}}}













