TaskNote Bridge-带Things 3和Apple Notes的Swift MCP服务器✅

](https://github.com/ragdollKB/taskNote-bridge-mcp/releases/latest)

一个本机macOS Swift应用程序，实现了完整的模型上下文协议（MCP）用于Things 3和Apple Notes集成的服务器。

状态: ✅ 生产就绪 -配备GUI监控的完整MCP服务器

🚀 快速安装

📥 下载并安装

下载最新版本
打开DMG 并将TaskNote Bridge拖动到应用程序中
启动应用程序 -MCP服务器自动启动
配置VS代码 使用以下设置

⚙️ Claude桌面配置

将此添加到您的Claude Desktop MCP服务器配置中：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

📝 备注：替换 /path/to/tasknote-bridge/ 使用您的实际安装目录。例如： - 如果您下载了该版本： /Users/[username]/Downloads/tasknote-bridge/ - 如果你克隆了repo： /Users/[username]/Projects/tasknote-bridge/ - 如果将其移动到应用程序： /Applications/TaskNote Bridge/

⚙️ VS代码配置

将此添加到您的VS代码中 settings.json:

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh",
                "args": []
            }
        }
    }
}

就是这样！ 🎉 您已准备好通过AI助手创建任务和笔记。

📋 需求

macOS12.0+（蒙特利或更高）
事情3：从Mac应用商店安装
苹果笔记：内置于macOS
VS代码：带MCP扩展

🎯 现在什么有效

# Test the stdio server (creates task in 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

# Expected output:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ Task 'Hello from VS Code!' created in Things 3","type":"text"}],"isError":false}}

# ✅ Check Things 3 - your task will be there!

用于GUI监控

# Build and run the macOS app
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# Server auto-starts with monitoring interface

🛠 完整功能集

本机macOS MCP服务器应用程序

完整的MCP服务器：使用Things 3和Apple Notes工具全面实现MCP协议的Swift
实时监控：带有实时活动跟踪的服务器状态仪表板
TCP传输：用于通用MCP客户端兼容性的基于网络的传输协议
日志流：具有过滤和搜索功能的实时服务器日志
连接管理：监视活动客户端连接和请求/响应活动
SwiftUI界面：用于服务器监控和控制的现代macOS界面

事物3整合

访问所有主要事项列表（收件箱、今天、即将到来等）
项目和区域管理
标签操作
高级搜索功能
最近的项目跟踪
详细的项目信息，包括检查表
支持嵌套数据（区域内的项目，项目内的待办事项）
直接在Things 3应用程序中打开特定任务

Apple Notes集成

创建带有标题、内容和标签的新笔记
按标题搜索笔记
检索笔记内容
列出所有笔记
直接在Apple notes应用程序中打开笔记
删除笔记
完整的AppleScript集成，实现无缝的macOS体验

安装

选项1：下载应用程序（推荐）

下载最新 TaskNote Bridge.app 从发布页

选项2：从源代码构建

如果你更喜欢从源代码构建，你需要：

Xcode 14.0或更新版本
macOS 13.0或更新版本

克隆存储库并构建：

# Clone the repository
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp

# Open in Xcode and build
open "TaskNote Bridge.xcodeproj"

配置

先决条件

任何与MCP兼容的AI助手或工具（Claude Desktop、带MCP扩展的VS Code、Cursor、Continue、Zed等）
事情3（必须在设置->常规中打开“启用事情URL”）
Apple Notes（用于笔记管理功能）
macOS 13.0或更高版本（SwiftUI和AppleScript集成所需）

🏗️ 项目架构

该项目提供 两种MCP服务器实现 对于不同的用例：

📱 TaskNote Bridge.app （GUI应用程序）

目的：带有可视化监控界面的macOS应用程序
运输：用于基于网络的连接的TCP服务器（端口8000）
特性：实时仪表板、连接监控、日志查看器
用例：当您想要对服务器活动进行可视化监控时
发射：从“应用程序”文件夹打开应用程序

📟 swift_mcp_sdio.swift （命令行服务器）

目的：基于stdio的轻量级MCP服务器
运输：标准输入/输出通信
特性：直接JSON-RPC消息处理，开销最小
用例: 建议用于Claude Desktop 以及大多数MCP客户端
发射：通过 launch_swift_mcp_stdio.sh 脚本

🔧 使用哪一个？

MCP客户端	推荐服务器	配置
克劳德桌面	✅ stdio脚本	`command: "/path/to/launch_swift_mcp_stdio.sh"`
VS代码MCP	✅ stdio脚本	与Claude Desktop相同
自定义TCP客户端	📱 GUI应用程序	连接到 `localhost:8000`
开发/测试	📱 GUI应用程序	可视化监控+TCP访问

💡 关键点：大多数MCP客户端（包括Claude Desktop）都期望基于stdio的通信，而不是TCP连接。

🔗 MCP客户端连接指南

TaskNote Bridge支持多种连接方法，可与各种MCP客户端配合使用。选择最适合您客户的方法：

🎯 克劳德桌面

配置Claude桌面 要使用基于stdio的MCP服务器：

打开克劳德桌面
点击设置齿轮(⚙️) 在左下角
选择“开发人员”
在“MCP服务器”部分，单击“编辑配置”
添加此配置:

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

📝 备注：替换 /path/to/tasknote-bridge/ 使用您的实际安装目录。常见路径： - 已下载版本: /Users/[username]/Downloads/tasknote-bridge/launch_swift_mcp_stdio.sh - 克隆存储库: /Users/[username]/Projects/tasknote-bridge/launch_swift_mcp_stdio.sh - 应用捆绑包安装: /Applications/TaskNote Bridge.app/Contents/Resources/launch_swift_mcp_stdio.sh \\\`

保存配置
重新启动克劳德桌面 应用更改

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

🔧 带有MCP扩展的VS代码

安装MCP扩展 对于VS代码：

- 打开VS代码扩展名（Cmd+Shift+X） - 搜索“模型上下文协议”并安装

配置VS代码 设置(settings.json):

{
    "mcp": {
        "servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

重新启动VS代码 加载MCP服务器

🖱️ 光标IDE

打开光标设置 （Cmd+，）
导航到扩展 → 模型上下文协议
添加服务器配置:

{
    "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
    "args": []
}

⚡ 继续（VS代码扩展）

安装继续扩展 VS代码
打开继续配置 （通常 ~/.continue/config.json)
添加MCP服务器:

{
    "mcpServers": [
        {
            "name": "tasknote-bridge",
            "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
            "args": []
        }
    ]
}

🚀 Zed编辑

打开Zed设置 （Cmd+，）
添加到您的设置.json:

{
    "assistant": {
        "mcp_servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh"
            }
        }
    }
}

🛠️ 自定义MCP客户端

对于任何自定义MCP客户端或应用程序：

tcp连接

主机: localhost
端口: 8000 （默认设置，可在TaskNote Bridge应用程序中配置）
协议：TCP与JSON-RPC 2.0

标准连接

命令: /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
运输：JSON-RPC 2.0标准输入/输出

📋 验证步骤

配置任何客户端后：

测试连接:

   # For stdio testing
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh

   # For TCP testing (if server is running)
   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

在事物3中验证 -测试任务应出现在您的收件箱中

🔍 连接问题疑难解答

克劳德桌面未连接

检查配置文件是否为有效的JSON
验证文件路径是否存在： /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
完全重新启动克劳德桌面
检查克劳德日志： ~/Library/Logs/Claude/mcp*.log

TCP连接问题

确保TaskNote Bridge应用程序正在运行
检查端口8000是否可用： lsof -i :8000
在TaskNote Bridge设置中尝试其他端口
验证防火墙设置是否允许本地连接

标准连接问题

验证脚本权限： ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
直接在终端中测试脚本
检查Things 3中是否启用了Things 3 URL→ 设置→ 将军

用于VS代码（带MCP扩展名）

首先，确保已安装并运行TaskNote Bridge应用程序。

安装VS代码的MCP扩展：

- 打开VS代码 - 转到扩展（Cmd+Shift+X） - 搜索“MCP”并安装官方MCP扩展

配置VS代码设置：

- 打开设置（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

重新启动VS Code以加载MCP服务器。

用法

在TaskNote Bridge应用程序中

从“应用程序”文件夹启动TaskNote Bridge应用程序。
该应用程序提供了一个原生macOS界面，用于：

- 查看你的Things 3任务、项目和领域 - 管理您的Apple Notes - 监控MCP服务器连接 - 实时查看活动日志

在克劳德桌面

连接后，您可以使用自然语言与TaskNote Bridge进行交互：

三个例子：

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

Apple Notes示例：

“根据今天的站立会议记录创建一个笔记”
“在我的笔记中搜索有关季度回顾的任何信息”
“记下我想尝试的新餐厅”
“显示我所有包含旅行信息的笔记”

在VS代码中

安装并配置MCP扩展后：

打开命令面板（Cmd+Shift+P）
键入“MCP”查看可用的MCP命令
使用“MCP：调用工具”与Things工具进行交互
或者使用任何支持MCP的AI助手来访问您的Things数据

适用于任何MCP兼容工具

该服务器遵循标准的MCP协议，可以与任何兼容MCP的应用程序或AI助手一起工作。只需配置您的工具，使用上述方法之一连接到Swift MCP服务器。

兼容的应用程序包括：

克劳德桌面
带有MCP扩展的VS代码
光标
继续
泽德
源代码图科迪
任何自定义MCP客户端实现

💡 更好集成的专业提示

克劳德桌面优化

创建自定义项目 在Claude中，提供有关如何使用Things 3和组织区域、项目、标签等的说明。
告诉克劳德要包括哪些信息 创建任务时（例如，任务描述中的相关细节）
与日历MCP服务器结合使用 让Claude为任务分配时间，并根据日历事件创建待办事项

多客户端使用

使用TCP模式 同时连接多个客户端
保持TaskNote Bridge应用程序打开 实时监控所有MCP活动
检查应用程序日志 如果您在工具调用中遇到任何问题

高级工作流

“使用艾森豪威尔矩阵评估我当前的待办事项”
“帮助我使用Things进行GTD风格的每周回顾”
“为\[项目名称\]创建包含子任务和截止日期的项目计划”
“分析我的任务完成模式并提出改进建议”

项目结构

TaskNote Bridge.app/          # The macOS Swift application
├── Contents/
│   ├── MacOS/                # Native Swift executable containing MCP server
│   │   └── TaskNote Bridge   # Main app with embedded MCP server
│   ├── Resources/            # Application resources
│   └── Info.plist            # App bundle configuration
├── TaskNote Bridge.xcodeproj/ # Xcode project
├── SwiftMCPServer.swift      # Core MCP server implementation
├── ThingsIntegration.swift   # Things 3 integration layer
├── NotesIntegration.swift    # Apple Notes integration layer
└── README.md                 # This documentation

可用工具

列表视图

get-inbox -从收件箱获取待办事项
get-today -今天拥有所有
get-upcoming -获取即将到来的待办事项
get-anytime -从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 -获取最近创建的项目

刀具参数

所有人

project_uuid （可选）-按项目筛选待办事项
include_items （可选，默认值：true）-包括检查表项目

获取项目/获取区域/获取标签

include_items （可选，默认值：false）-包括包含的项目

搜索高级

status -按状态筛选（未完成/已完成/已取消）
start_date -按开始日期（YYYY-MM-DD）筛选
deadline -按截止日期筛选（YYYY-MM-DD）
tag -按标签筛选
area -按区域UUID筛选
type -按项目类型（待办事项/项目/标题）筛选

获取最新信息

period -时间段（例如，“3d”、“1w”、“2m”、“1年”）

全部开放

title -要搜索和打开的待办事项的标题或部分标题

笔记打开

title -在Apple Notes中打开的笔记的确切标题

故障排除

连接问题

克劳德桌面

检查配置文件：确保JSON配置有效且格式正确
验证文件路径：确保 /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh 存在
重新启动克劳德：配置更改后完全退出并重新启动Claude Desktop
检查日志：查看克劳德日志 ~/Library/Logs/Claude/mcp*.log

TCP连接问题

应用程序正在运行：确保TaskNote Bridge应用程序在TCP服务器启动的情况下运行
端口可用性：检查端口8000是否可用 lsof -i :8000
防火墙设置：验证macOS防火墙是否允许本地连接
尝试其他端口：如果需要，请更改TaskNote Bridge应用程序设置中的端口

标准连接问题

脚本权限：验证脚本是否可执行： ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
直接测试：在终端中测试脚本以确保其正常工作
事情3 URL：确保在Things 3中打开“启用Things URL”→ 设置→ 将军

工具执行问题

该服务器包括全面的错误处理功能，用于：

无效的UUID和格式错误的请求
缺少必要参数
Things 3数据库访问错误
Apple Notes AppleScript执行错误
数据格式和序列化错误

所有错误都记录在描述性消息中。查看MCP日志：

# Follow Claude Desktop logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Check TaskNote Bridge app logs
# Open TaskNote Bridge app and view the built-in log viewer

# Test server directly
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应用程序授予必要的权限→ 安全与隐私

“事情3没有响应”错误

确保Things 3已安装并至少启动过一次
检查Things 3设置中是否启用了“启用Things URL”
尝试重新启动Things 3

“拒绝访问Apple Notes”错误

授予TaskNote Bridge权限以在“系统首选项”中控制Apple Notes→ 安全与隐私→ 自动化
确保Apple Notes应用程序不受任何安全软件的限制

🚨 故障排除

Claude桌面连接问题

“请求超时”/服务器没有响应

如果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脚本
重新启动克劳德桌面
连接现在应该可以正常工作而不会超时

验证服务器是否正常工作

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

Tasknote Bridge MCP

快速接入

详细介绍

TaskNote Bridge-带Things 3和Apple Notes的Swift MCP服务器✅

🚀 快速安装

📥 下载并安装

⚙️ Claude桌面配置

⚙️ VS代码配置

📋 需求

🎯 现在什么有效

用于GUI监控

🛠 完整功能集

本机macOS MCP服务器应用程序

事物3整合

Apple Notes集成

安装

选项1：下载应用程序（推荐）

选项2：从源代码构建

配置

先决条件

🏗️ 项目架构

📱 TaskNote Bridge.app （GUI应用程序）

📟 swift_mcp_sdio.swift （命令行服务器）

🔧 使用哪一个？

🔗 MCP客户端连接指南

🎯 克劳德桌面

🔧 带有MCP扩展的VS代码

🖱️ 光标IDE

⚡ 继续（VS代码扩展）

🚀 Zed编辑

🛠️ 自定义MCP客户端

tcp连接

标准连接

📋 验证步骤

🔍 连接问题疑难解答

克劳德桌面未连接

TCP连接问题

标准连接问题

用于VS代码（带MCP扩展名）

用法

用法

在TaskNote Bridge应用程序中

在克劳德桌面

在VS代码中

适用于任何MCP兼容工具

💡 更好集成的专业提示

克劳德桌面优化

多客户端使用

高级工作流

项目结构

可用工具

列表视图

基本操作

标签操作

搜索操作

基于时间的操作

刀具参数

所有人

获取项目/获取区域/获取标签

搜索高级

获取最新信息

全部开放

笔记打开

故障排除

连接问题

克劳德桌面

TCP连接问题

标准连接问题

工具执行问题

常见错误解决方案

“权限被拒绝”错误

“事情3没有响应”错误

“拒绝访问Apple Notes”错误

🚨 故障排除

Claude桌面连接问题

“请求超时”/服务器没有响应

验证服务器是否正常工作

目录标签

接入字段

权限和风险