shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

tasknote-bridge-mcp

TaskNote Bridge是一个原生macOS Swift应用，实现了完整的MCP协议服务器，用于Things 3和Apple Notes的AI助手集成。

article

README

🚀 TaskNote Bridge - 支持Things 3与Apple Notes的Swift MCP服务器 ✅

TaskNote Bridge是一款原生macOS Swift应用程序，它实现了一个完整的模型上下文协议（MCP）服务器，用于集成Things 3和Apple Notes。借助该应用，用户可以通过AI助手在这两个工具中便捷地创建任务和笔记。

下载最新版本

🚀 快速开始

📥 下载与安装

  1. 下载最新版本
  2. 打开DMG文件，将TaskNote Bridge拖移到“应用程序”文件夹
  3. 启动应用程序 - MCP服务器将自动启动
  4. 按照以下设置配置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 13.0或更高版本（SwiftUI和AppleScript集成所需）

💻 使用示例

基础用法

# 测试stdio服务器（在Things 3中创建任务！）
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "来自VS Code的问候！", "tags": ["测试"]}}}' | ./launch_swift_mcp_stdio.sh

# 预期输出：
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ 任务'来自VS Code的问候！'已在Things 3中创建","type":"text"}],"isError":false}}

# ✅ 检查Things 3 - 你的任务将显示在那里！

高级用法

# 构建并运行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服务器：

  1. 打开Claude Desktop
  2. 点击左下角的设置齿轮（⚙️）
  3. 选择“开发者”
  4. 在“MCP服务器”部分，点击“编辑配置”
  5. 添加以下配置：
{
    "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
  1. 保存配置
  2. 重启Claude Desktop以应用更改

✅ 成功提示

Claude Desktop现在将通过stdio传输进行连接，这是MCP通信推荐且最可靠的方法。

🔧 VS Code与MCP扩展

  1. 为VS Code安装MCP扩展：
    • 打开VS Code扩展（Cmd+Shift+X）
    • 搜索“Model Context Protocol”并安装
  2. 配置VS Code设置（settings.json）：
{
    "mcp": {
        "servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}
  1. 重启VS Code以加载MCP服务器

🖱️ Cursor IDE

  1. 打开Cursor设置（Cmd+,）
  2. 导航至扩展 → “Model Context Protocol”
  3. 添加服务器配置：
{
    "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
    "args": []
}

⚡ Continue（VS Code扩展）

  1. 在VS Code中安装Continue扩展
  2. 打开Continue配置（通常为~/.continue/config.json）
  3. 添加MCP服务器：
{
    "mcpServers": [
        {
            "name": "tasknote-bridge",
            "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
            "args": []
        }
    ]
}

🚀 Zed编辑器

  1. 打开Zed设置（Cmd+,）
  2. 添加到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的标准输入/输出

📋 验证步骤

配置任何客户端后：

  1. 测试连接：
# 进行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
  1. 检查可用工具 - 你应该看到类似以下的工具：
    • bb7_add-todo
    • bb7_add-project
    • bb7_get-today
    • bb7_notes-create
    • 等等...
  2. 测试任务创建：
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "来自MCP的测试！", "tags": ["测试"]}}}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
  1. 在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
对于VS Code（安装了MCP扩展）
  1. 首先，确保已安装并运行TaskNote Bridge应用程序。
  2. 为VS Code安装MCP扩展：
    • 打开VS Code
    • 转到扩展（Cmd+Shift+X）
    • 搜索“MCP”并安装官方MCP扩展
  3. 配置VS Code设置：
    • 打开设置（Cmd+,）
    • 点击右上角的“打开设置（JSON）”
    • 添加以下配置：
{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

⚠️ 重要提示

请将路径替换为实际安装应用程序的位置。若将其移至“应用程序”文件夹，请使用：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh

  1. 重启VS Code以加载MCP服务器。

使用方法

在TaskNote Bridge应用程序中

  1. 从“应用程序”文件夹启动TaskNote Bridge应用程序。
  2. 该应用程序提供了一个原生macOS界面，用于：
    • 查看Things 3任务、项目和区域
    • 管理Apple Notes
    • 监控MCP服务器连接
    • 实时查看活动日志

在Claude Desktop中

连接后，你可以使用自然语言与TaskNote Bridge交互： Things 3示例：

  • “我今天的待办事项列表有哪些？”
  • “创建一个下周为海滩度假打包的待办事项”
  • “创建一个阵亡将士纪念日烧烤项目，并包含规划任务”
  • “显示我所有与工作相关的任务”
  • “将购物任务标记为已完成”
  • “添加一个明天给妈妈打电话的任务”

Apple Notes示例：

  • “创建一个包含今天站立会议会议记录的笔记”
  • “在我的笔记中搜索有关季度审查的内容”
  • “记录我想尝试的新餐厅”
  • “显示所有包含旅行信息的笔记”

在VS Code中

安装并配置MCP扩展后：

  1. 打开命令面板（Cmd+Shift+P）
  2. 输入“MCP”以查看可用的MCP命令
  3. 使用“MCP: Call Tool”与Things工具交互
  4. 或使用任何支持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
  • 检查日志：查看Claude日志~/Library/Logs/Claude/mcp*.log
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消息处理

解决方法：

  1. 更新Claude Desktop配置以使用stdio脚本
  2. 重启Claude Desktop
  3. 现在连接应该不会超时。
验证服务器是否正常工作

直接测试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":{}}}}
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端