ulysses-mcp

🚀 Ulysses MCP Server

Ulysses MCP Server 是一个 MCP（模型上下文协议）服务器，可让 AI 助手与 macOS 上的 Ulysses 写作应用程序进行交互，为写作流程带来自动化和智能化的提升。

🚀 快速开始

Ulysses MCP Server 提供了一系列工具，可通过 Ulysses 的 x-callback-url API 实现自动化操作。借助该服务器，像 Claude、Cline 等 AI 助手和其他 MCP 兼容客户端能够：

• 📝 创建和管理文档 - 创建包含内容的新文档。
• 📁 使用分组进行组织 - 创建和管理文件夹结构。
• ✏️ 添加内容 - 向现有文档中插入或追加文本。
• 🏷️ 附加元数据 - 为文档添加注释、关键词和图像。
• 📖 读取内容 - 提取文档内容和元数据（需要授权）。
• 🧭 导航 - 打开特定的文档、分组或特殊部分。
• 🔧 修改 - 移动、复制、重命名和删除项目（需要授权）。

✨ 主要特性

• 全面的自动化工具：提供 23 种工具，涵盖内容创建、修改、导航、信息获取和授权等多个方面。
• 多客户端支持：与 Claude Desktop、Cline 等 MCP 兼容客户端集成。
• 严格的安全机制：包括输入验证、访问令牌处理和速率限制等。
• 本地运行：服务器完全本地运行，保护用户隐私。

📦 安装指南

使用 npm

npm install ulysses-mcp

从源代码安装

git clone https://github.com/sonofagl1tch/ulysses-mcp.git
cd ulysses-mcp
npm install
npm run build

构建辅助应用程序

⚠️ 重要提示

出于安全原因，此仓库中不包含辅助应用程序的二进制文件。安装后，您必须在本地进行构建。

安装完成后，您需要构建辅助应用程序（回调操作所需）：

npm run build-helper

此命令将创建一个小型的 macOS 应用程序，用于处理来自 Ulysses 的回调。该辅助应用程序：

• 在需要时自动运行（无需手动启动）。
• 注册一个自定义 URL 方案 (ulysses-mcp-callback://)。
• 启用需要回调的操作（授权、读取内容等）。
• 切勿将其提交到版本控制（已包含在 .gitignore 中）。

更多详细信息，请参阅 辅助应用程序文档。

💻 使用示例

基础用法

创建新文档

// 创建每日日记条目
{
  "tool": "ulysses_new_sheet",
  "arguments": {
    "text": "# Journal Entry - October 23, 2025\n\nToday I...",
    "group": "/Journal",
    "format": "markdown"
  }
}

添加关键词

// 为文档添加标签以便组织
{
  "tool": "ulysses_attach_keywords",
  "arguments": {
    "id": "sheet-identifier-here",
    "keywords": "Draft,Blog,Technical"
  }
}

高级用法

读取内容（需要授权）

// 首先，进行授权
{
  "tool": "ulysses_authorize",
  "arguments": {
    "appname": "My AI Assistant"
  }
}
// 在 Ulysses 中批准授权后，使用令牌读取内容
{
  "tool": "ulysses_read_sheet",
  "arguments": {
    "id": "sheet-identifier-here",
    "text": "YES",
    "access_token": "your-access-token"
  }
}

📚 详细文档

如需了解有关架构、安全、隐私和身份验证的详细信息，请参阅 docs/ 目录中的综合文档：

• 架构 - 系统架构、数据流和技术细节。
• 身份验证 - 授权模型、访问令牌和安全性。
• 隐私与安全 - 隐私保证、安全功能和验证。
• 文档索引 - 完整的文档概述。

🔧 技术细节

获取文档标识符

许多操作都需要文档和分组的标识符。以下是获取它们的方法：

在 Mac 上

1. 在文档列表中选择一个文档。
2. 按 ⌘C（Command-C）复制其标识符。
3. 或者：按住 ⌥（Option/Alt）键并右键单击 → “复制回调标识符”。

在 iOS/iPadOS 上

1. 长按一个文档。
2. 选择 “共享” → “共享快捷方式标识符” → “复制”。
3. 对于分组：点击 … 按钮 → 共享 → 共享快捷方式标识符。

标识符类似于：H8zLAmc1I0njH-0Ql-3YGQ。

授权

某些操作（读取内容、进行破坏性更改）需要授权：

1. 使用 ulysses_authorize 工具并提供您的应用程序名称。
2. 在 Ulysses 中批准授权请求。
3. 复制提供的访问令牌。
4. 在后续需要授权的操作中使用该令牌。

访问令牌在 Ulysses 偏好设置中被撤销之前一直有效。

安全

⚠️ 重要提示

虽然此 MCP 服务器完全在本地运行且私密，但根据您的配置，您的 AI 助手可能会将数据发送到云服务：

• 云 AI（Claude Desktop、ChatGPT 等）：您的写作内容可能会被发送到他们的服务器。
• 本地 AI（Ollama、LM Studio）：完全保持本地运行 ✅。

对于敏感内容，请使用仅本地的 AI 模型。详细信息请参阅 隐私文档。

访问令牌处理

⚠️ 重要安全警告：

• 访问令牌可完全访问您的 Ulysses 库。请像对待密码一样对待它们。
• 切勿将令牌提交到版本控制 或公开共享。
• 如果需要在会话之间保留令牌，请安全存储。
• 通过 Ulysses → 偏好设置 → 隐私撤销不再需要的令牌。
• 速率限制：破坏性操作限制为每分钟 10 次，以防止意外损坏。

输入验证

此服务器实现了全面的输入验证：

• 验证必需参数的存在和非空值。
• 文本输入有合理的长度限制（内容为 1MB，注释为 100KB）。
• 枚举值根据允许的选项进行验证。
• 所有操作都根据白名单进行验证。
• 通过安全的命令执行防止命令注入。

安全功能

• ✅ 使用 execFile 而非 exec 防止命令注入。
• ✅ 对所有参数进行输入验证。
• ✅ 操作白名单验证。
• ✅ 对破坏性操作进行速率限制。
• ✅ 清理错误消息。
• ✅ 日志中不暴露敏感数据。

报告安全问题

如果您发现安全漏洞，请发送电子邮件至 sonofagl1tch@pebcakconsulting.com 或在 GitHub 上开启安全咨询。请勿公开报告安全漏洞。

用例

内容创建工作流程

• 博客写作：使用 AI 生成文章并保存到 Ulysses。
• 每日日记：自动创建带日期的条目。
• 笔记记录：在 AI 辅助下快速捕获信息。
• 研究组织：在 AI 帮助下整理研究内容。

内容管理

• 批量标记：使用关键词组织内容。
• 内容审核：以编程方式分析文档。
• 库组织：自动管理结构和归档。
• 备份与存档：系统地导出内容。

AI 辅助写作

• 内容生成：AI 写作并保存到 Ulysses。
• 编辑辅助：读取、建议和更新内容。
• 研究整合：获取并整合研究内容。
• 大纲扩展：将简报扩展为完整文章。

限制与未来增强

当前限制

MCP 服务器受 Ulysses x-callback-url API 功能的限制。Ulysses GUI 中可用的某些功能目前无法通过 API 实现：

• ❌ 搜索功能 - 无法按内容或元数据搜索文档。
• ❌ 统计信息 - 无法检索字数、字符数或阅读时间。
• ❌ 导出操作 - 无法将文档导出为 PDF、DOCX 或其他格式。
• ❌ 发布 - 无法直接发布到 WordPress、Medium 或其他平台。
• ❌ 目标和指标 - 无法设置或检索写作目标。
• ❌ 文档历史 - 无法访问修订历史或版本控制。
• ❌ 过滤器 - 无法按日期、关键词或其他标准过滤文档。
• ❌ 收藏管理 - 无法通过 API 将文档标记/取消标记为收藏。
• ❌ 主题/外观 - 无法控制 Ulysses 的外观或编辑器设置。

已提交的功能请求

已向 Ulysses 提交了扩展 x-callback-url API 功能的请求。如果您希望看到更多功能，可以考虑：

1. 对功能请求进行投票（链接待定）。
2. 联系 Ulysses 支持 表达对 API 扩展的兴趣。
3. 分享用例 说明增强 API 访问的好处。

解决方法

对于某些限制，存在部分解决方法：

• 统计信息：读取文档内容并在本地计算。
• 搜索：使用 get-root-items 并设置 recursive=YES 进行本地过滤。
• 导出：读取内容并使用外部工具进行导出。

潜在的未来增强

如果 Ulysses 扩展其 x-callback-url API，此 MCP 服务器可能支持：

• 🔮 跨库全文搜索。
• 🔮 将文档导出为各种格式。
• 🔮 检索写作统计信息和分析。
• 🔮 管理写作目标和指标。
• 🔮 访问修订历史。
• 🔮 高级过滤和排序。
• 🔮 发布集成。

注意：这些增强取决于 Ulysses 扩展其 x-callback-url API。MCP 服务器设计为在新 API 功能可用时易于更新。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

开发

构建

npm run build

监听更改

npm run watch

使用 MCP Inspector 进行测试

npm run inspector

项目结构

ulysses-mcp/
├── src/
│   └── index.ts          # 主服务器实现
├── build/                # 编译后的 JavaScript 输出
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

API 参考

此服务器实现了 Ulysses x-callback-url API 版本 3。

详细的 API 文档请参阅：

• Ulysses x-callback-url 文档
• 模型上下文协议

故障排除

服务器无法连接

• 验证 Ulysses 是否安装在您的 Mac 上。
• 检查 MCP 配置中的构建路径。
• 重新构建服务器：npm run build。
• 重启 MCP 客户端。

授权问题

• 运行 ulysses_authorize 获取新的令牌。
• 在 Ulysses 提示时批准授权请求。
• 复制并保存访问令牌。
• 检查令牌是否在 Ulysses 偏好设置中被撤销。

文档标识符无效

• 验证 22 字符的标识符格式。
• 确保文档仍存在于 Ulysses 中。
• 注意：如果项目移动，外部文件夹标识符可能会更改。

贡献

欢迎贡献！请随时提交拉取请求。

1. 分叉仓库。
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m 'Add amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打开拉取请求。

支持

• 问题反馈：GitHub 问题
• Ulysses 支持：ulysses.app/support
• MCP 文档：modelcontextprotocol.io

为 Ulysses 和 AI 社区用心打造 ❤️