内容
# OmniFocus MCP 服务器
一款高性能、原生的 macOS [MCP](https://modelcontextprotocol.io) 服务器，用于 [OmniFocus](https://www.omnigroup.com/omnifocus)。
单个通用二进制文件 — 无需 Node.js，无需 Python，无运行时依赖。
## 功能
- **快速**: 原生 Swift 二进制文件，支持 TTL 缓存、服务器端筛选和字段投影。
- **安全**: 破坏性操作默认使用 dry-run，并使用 HMAC-SHA256 确认令牌流。
- **有界**: 所有查询都有默认限制和光标分页。不会导出完整的数据库。
- **专业感知**: 检测 OmniFocus Pro 与标准版。在标准模式下，退回到 URL 方案捕获。
- **视角**: 通过窗口内容树 API 查询任务 - 内置或自定义。
## 要求
- macOS 14.0+
- OmniFocus 4（或 3）
- OmniFocus Pro 许可证（用于完全自动化；标准版仅支持捕获模式）
- 系统偏好设置 → 隐私和安全 → 自动化：允许 `omnifocus-mcp-server` 控制 OmniFocus
## 安装
### 直接下载
从 [GitHub Releases](https://github.com/mryanb/omnifocus-mcp-server/releases) 下载通用二进制文件：
```bash
curl -L -o omnifocus-mcp-server https://github.com/mryanb/omnifocus-mcp-server/releases/latest/download/omnifocus-mcp-server-universal
chmod +x omnifocus-mcp-server
sudo mv omnifocus-mcp-server /usr/local/bin/
```
### 从源代码构建
```bash
git clone https://github.com/mryanb/omnifocus-mcp-server.git
cd omnifocus-mcp-server
swift build -c release
cp .build/release/omnifocus-mcp-server /usr/local/bin/
```
## Claude 桌面配置
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"omnifocus": {
"command": "/usr/local/bin/omnifocus-mcp-server",
"env": {
"OMNIFOCUS_MCP_LOG_LEVEL": "info"
}
}
}
}
```
## 工具
### 读取工具（需要 OmniFocus Pro）
| 工具 | 描述 |
|------|-------------|
| `diagnostics` | 服务器健康、能力模式、缓存统计 |
| `list_inbox` | 任务收件箱（有界、分页） |
| `list_today` | 今日到期或延迟的任务 |
| `list_flagged` | 标记为未完成的任务 |
| `list_forecast` | 过期 + 今日到期 + 标记， 按到期日期排序 |
| `list_projects` | 项目状态筛选 |
| `list_tags` | 所有标签 |
| `list_perspectives` | 所有内置和自定义视角 |
| `get_perspective_tasks` | 特定视角的任务 |
| `get_task_by_id` | 单个任务， 按稳定 ID |
| `search_tasks` | 筛选搜索， 与 AND 逻辑 |
| `get_task_count` | 计数匹配任务， 无需返回数据 |
### 修改工具（需要 OmniFocus Pro）
| 工具 | 描述 |
|------|-------------|
| `create_task` | 在收件箱或项目中创建任务 |
| `update_task` | 基于补丁的更新， 带有 dry-run/确认 |
| `batch_update_tasks` | 批量更新（配置门控） |
### 标准模式工具（无需 Pro）
| 工具 | 描述 |
|------|-------------|
| `create_task_via_url` | 通过 URL 方案创建（打开 OmniFocus） |
| `open_task_url` | 通过 ID 在 OmniFocus 中打开任务 |
## 工具示例
### 列出收件箱任务
```json
{
"name": "list_inbox",
"arguments": {
"limit": 10,
"fields": ["id", "name", "dueDate", "flagged"]
}
}
```
### 每日预测
```json
{
"name": "list_forecast",
"arguments": {
"limit": 50,
"fields": ["id", "name", "dueDate", "flagged", "projectName", "tagNames"]
}
}
```
### 获取自定义视角任务
```json
{
"name": "get_perspective_tasks",
"arguments": {
"id": "abc123",
"type": "custom",
"fields": ["id", "name", "dueDate", "projectName", "tagNames"]
}
}
```
### 搜索任务
```json
{
"name": "search_tasks",
"arguments": {
"query": "report",
"project": "Work",
"flagged": true,
"limit": 20
}
}
```
### 创建任务
```json
{
"name": "create_task",
"arguments": {
"name": "Review Q4 report",
"projectId": "abc123",
"dueDate": "2026-03-15T17:00:00Z",
"flagged": true,
"tagNames": ["Work", "Important"]
}
}
```
### 更新任务（两步破坏性更改）
步骤 1 — dry run（默认）：
```json
{
"name": "update_task",
"arguments": {
"id": "dXL1Kdp4XCx",
"patch": {
"status": "complete"
}
}
}
```
响应包括 `confirm_token`。
步骤 2 — 应用：
```json
{
"name": "update_task",
"arguments": {
"id": "dXL1Kdp4XCx",
"patch": {
"status": "complete"
},
"dry_run": false,
"confirm_token": "eyJ0YXNrX2lkIjo...abc123"
}
}
```
### 字段投影
所有列表工具都接受 `fields` 参数。 默认值为最小（`id`, `name`, `status`, `flagged`, `dueDate`）。 根据需要请求更多字段：
```json
{
"name": "list_inbox",
"arguments": {
"fields": ["id", "name", "note", "dueDate", "tagNames", "projectName"]
}
}
```
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `OMNIFOCUS_MCP_LOG_LEVEL` | `info` | `debug`, `info`, `warning`, `error` |
| `OMNIFOCUS_MCP_BULK_OPS` | `false` | 启用批量操作 |
| `OMNIFOCUS_MCP_DELETE_ENABLED` | `false` | 启用删除能力 |
| `OMNIFOCUS_MCP_TOOL_ALLOWLIST` | （全部） | 以逗号分隔的工具名称 |
| `OMNIFOCUS_MCP_DEFAULT_LIMIT` | `50` | 默认结果限制 |
| `OMNIFOCUS_MCP_MAX_LIMIT` | `200` | 最大结果限制 |
| `OMNIFOCUS_MCP_CACHE_ENABLED` | `true` | 启用 TTL 缓存 |
### 配置文件（可选）
`~/.config/omnifocus-mcp/config.json`:
```json
{
"log_level": "info",
"bulk_ops": false,
"enable_delete": false,
"default_limit": 50
}
```
环境变量覆盖配置文件值。
## 安全
### 数据访问
- 服务器通过 Omni Automation（JavaScript）控制 OmniFocus， 使用 `osascript`
- **不** 直接读取 OmniFocus 数据库文件
- 需要 macOS 自动化权限（首次使用时，系统偏好设置提示）
- 所有通信通过 MCP stdio 进行 — 无网络访问
### 日志记录
- 日志仅输出到 **stderr** （stdout 保留给 MCP 协议）
- 任务备注 **永远不会** 被记录（可能包含敏感数据）
- 设置 `OMNIFOCUS_MCP_LOG_LEVEL=error` 以实现最小日志记录
### 安全控制
- **破坏性操作** 默认 `dry_run: true`
- **不可逆转的转换** （完成，删除）需要 HMAC-SHA256 `confirm_token`
- **批量操作** 默认禁用（`OMNIFOCUS_MCP_BULK_OPS=true` 启用）
- **删除** 默认禁用（`OMNIFOCUS_MCP_DELETE_ENABLED=true` 启用）
- **工具允许列表** 限制公开的工具
## 故障排除
### "OmniFocus 未运行"
在使用服务器之前启动 OmniFocus。 服务器不会自动启动 OmniFocus。
### "capability_unavailable" 错误
您正在运行 OmniFocus 标准版（非 Pro）。 自动化需要 Pro。
在标准模式下，仅 `create_task_via_url` 和 `open_task_url` 可用。
### 权限被拒绝
macOS 需要授予自动化权限：
1. 系统偏好设置 → 隐私和安全 → 自动化
2. 找到 `omnifocus-mcp-server`（或运行它的终端）
3. 启用对 OmniFocus 的访问
### 服务器未连接
检查 Claude 桌面配置语法。 验证二进制文件路径是否正确：
```bash
which omnifocus-mcp-server
omnifocus-mcp-server # 应该在 stderr 上打印 "[omnifocus-mcp-server] Starting..."
```
### 视角任务需要打开窗口
`get_perspective_tasks` 使用 OmniFocus 窗口内容树 API。 必须至少有一个 OmniFocus 窗口打开（不仅仅在后台运行）。
## 协议
- **MCP 版本**: `2025-11-25`（固定）
- **传输**: stdio（JSON-RPC，每行分隔）
- **SDK**: [modelcontextprotocol/swift-sdk](https://github.com/modelcontextprotocol/swift-sdk) v0.11.0
## 许可证
[MIT](LICENSE)
