Ulysses MCP服务器
 
MCP（模型上下文协议）服务器，使AI助手能够与 尤利西斯 在macOS上编写应用程序。
博客
概述
该MCP服务器通过其x-callback-url API提供了全面的工具来自动化Ulysses，使Claude、Cline和其他MCP-兼容客户端等人工智能助手能够：
- 📝 创建和管理工作表 -创建包含内容的新文档
- 📁 分组组织 -创建和管理文件夹结构
- ✏️ 添加内容 -在现有工作表中插入或附加文本
- 🏷️ 附加元数据 -在工作表中添加注释、关键字和图像
- 📖 阅读内容 -提取工作表内容和元数据（需要授权）
- 🧭 导航 -打开特定的表、组或特殊部分
- 🔧 修改 -移动、复制、重命名和删除项目（需要授权）
先决条件
- macOS（Ulysses仅适用于Mac/iOS）
- 尤利西斯 安装
- Node.js 18.0.0或更高版本
- MCP兼容客户端（Claude Desktop、Cline等）
安装
使用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这创建了一个处理Ulysses回调的小型macOS应用程序。助手应用程序：
- 需要时自动运行（无需手动启动）
- 注册自定义URL方案(
ulysses-mcp-callback://) - 启用需要回调的操作（授权、读取内容等）
- 永远不应该致力于版本控制 （已在.gitignore中）
有关更多详细信息，请参阅 助手应用程序文档.
配置
适用于克劳德桌面
添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"ulysses": {
"command": "node",
"args": ["/path/to/ulysses-mcp/build/index.js"]
}
}
}对于Cline（VS代码扩展）
添加到Cline的MCP设置中：
macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
{
"mcpServers": {
"ulysses": {
"disabled": false,
"autoApprove": [],
"type": "stdio",
"command": "node",
"args": ["/path/to/ulysses-mcp/build/index.js"]
}
}
}对于其他MCP客户端
有关通过stdio传输添加MCP服务器的信息，请参阅客户的文档。
可用工具
服务器提供23个工具，分为以下几类：
内容创作
ulysses_new_sheet-创建包含内容的新工作表ulysses_new_group-创建新组（文件夹）
内容修改
ulysses_insert-在现有工作表中插入/附加文本ulysses_attach_note-在纸张上附上注释ulysses_attach_keywords-添加关键字（标签）ulysses_attach_image-附加图像（base64）
导航
ulysses_open-打开特定工作表或组ulysses_open_all-打开“全部”部分ulysses_open_recent-打开“最后7天”ulysses_open_favorites-打开“收藏夹”
信息与授权
ulysses_get_version-获取Ulysses和API版本ulysses_authorize-申请图书馆访问权限（阅读需要）ulysses_read_sheet-读取工作表内容（需要身份验证）ulysses_get_item-获取工作表/组信息（需要身份验证）ulysses_get_root_items-获取库结构（需要身份验证）
高级操作（需要授权）
ulysses_move-移动工作表/组ulysses_copy-复制工作表/组ulysses_trash-将物品移至垃圾箱ulysses_set_group_title-重命名组ulysses_set_sheet_title-更改工作表标题ulysses_remove_keywords-删除关键字ulysses_update_note-更新现有笔记ulysses_remove_note-删除笔记
用法示例
创建新工作表
// Create a daily journal entry
{
"tool": "ulysses_new_sheet",
"arguments": {
"text": "# Journal Entry - October 23, 2025\n\nToday I...",
"group": "/Journal",
"format": "markdown"
}
}添加关键字
// Tag a sheet for organization
{
"tool": "ulysses_attach_keywords",
"arguments": {
"id": "sheet-identifier-here",
"keywords": "Draft,Blog,Technical"
}
}阅读内容（需要授权）
// First, authorize
{
"tool": "ulysses_authorize",
"arguments": {
"appname": "My AI Assistant"
}
}
// After approving in Ulysses, use the token to read
{
"tool": "ulysses_read_sheet",
"arguments": {
"id": "sheet-identifier-here",
"text": "YES",
"access_token": "your-access-token"
}
}获取工作表标识符
许多操作都需要表和组标识符。以下是获取它们的方法：
在Mac上
- 在图纸列表中选择一张图纸
- 按⌘C（命令-C）复制其标识符
- 或者：按住⌥（option/alt）并单击鼠标右键→ “复制回拨标识符”
在iOS/iPad上
- 按住一张纸
- 选择“共享”→ “共享快捷方式标识符”→ “复制”
- 对于组：点击
…按钮→ 分享→ 共享快捷方式标识符
标识符看起来像： H8zLAmc1I0njH-0Ql-3YGQ
授权
某些操作（读取内容、破坏性更改）需要授权：
- 使用
ulysses_authorize带有应用程序名称的工具 - 批准Ulysses中的授权请求
- 复制提供的访问令牌
- 在后续需要令牌的操作中使用令牌
访问令牌将一直存在，直到在Ulysses首选项中被撤销。
安全
⚠️ 隐私警告：虽然此MCP服务器完全是本地和私有的，但您的AI助手可能会根据您的配置将数据发送到云服务： - 云AI（克劳德桌面、ChatGPT等）：您的文章可能会被发送到他们的服务器 - 本地AI（Ollama，LM工作室）：完全本地化✅ 对于敏感内容，使用仅限本地的AI模型。看 隐私文件 了解详情。
访问令牌处理
⚠️ 重要安全警告:
- 访问令牌提供对Ulysses库的完全访问权限。把它们当作密码。
- 从不将令牌提交到版本控制 或者公开分享。
- 安全地存储令牌 如果你需要在会话之间坚持它们。
- 撤销代币 你不再需要通过尤利西斯→ 偏好设置→ 隐私。
- 速率限制：破坏性操作限制在每分钟10次，以防止意外损坏。
输入验证
此服务器实现了全面的输入验证：
- 验证所需参数的存在值和非空值
- 文本输入有合理的长度限制（内容1MB，注释100KB）
- 枚举值根据允许的选项进行验证
- 所有操作都会根据白名单进行验证
- 通过安全命令执行防止命令注入
安全特性
- ✅ 使用命令注入保护
execFile而不是exec - ✅ 所有参数的输入验证
- ✅ 操作白名单验证
- ✅ 破坏性操作的速率限制
- ✅ 山宁泰错误消息
- ✅ 日志中没有敏感数据泄露
报告安全问题
如果您发现安全漏洞，请发送电子邮件至 或者在GitHub上发布安全公告。不要公开安全漏洞问题。
用例
内容创建工作流
- 博客写作：使用AI生成帖子并保存到Ulysses
- 每日日志：自动创建日期条目
- 记笔记：借助人工智能快速捕捉
- 研究机构：在人工智能的帮助下进行结构研究
内容管理
- 批量标记：使用关键字组织内容
- 内容审查：以编程方式分析图纸
- 图书馆组织：自动化结构和归档
- 备份和归档：系统地导出内容
人工智能辅助写作
- 内容生成：AI写作，拯救尤利西斯
- 编辑协助：阅读、建议、更新内容
- 研究整合：获取并整合研究
- 大纲扩展：将简报变成整篇文章
限制和未来的增强
当前限制
MCP服务器受到Ulysses x-callback-url API功能的限制。Ulysses GUI中的某些功能目前无法通过API使用：
目前不支持：
- ❌ 搜索功能 -无法按内容或元数据跨工作表搜索
- ❌ 统计 -无法检索字数、字符数或阅读时间
- ❌ 出口业务 -无法将工作表导出为PDF、DOCX或其他格式
- ❌ 出版 -无法直接发布到WordPress、Medium或其他平台
- ❌ 目标和指标 -无法设置或检索写作目标
- ❌ 工作表历史记录 -无法访问修订历史记录或版本控制
- ❌ 过滤器 -无法按日期、关键字或其他条件筛选工作表
- ❌ 收藏夹管理 -无法通过API将工作表标记/取消标记为收藏夹
- ❌ 主题/外观 -无法控制Ulysses外观或编辑器设置
功能请求已提交
已经向Ulysses提交了一个功能请求，以扩展具有附加功能的x-callback-url API。如果您想看到更多功能，请考虑：
- 投票 在功能请求上（可用时链接待定）
- 联系Ulysses支持 表达对API扩展的兴趣
- 共享用例 将受益于增强的API访问
变通方法
对于某些限制，存在部分解决方法：
- 统计：读取工作表内容并在本地计算
- 搜索：使用
get-root-items随着recursive=YES并在本地进行过滤 - 出口：使用外部工具读取内容并导出
未来潜在的增强功能
如果扩展了Ulysses API，则此MCP服务器可能支持：
- 🔮 在整个库中进行全文搜索
- 🔮 将工作表导出为各种格式
- 🔮 检索写作统计和分析
- 🔮 管理写作目标和指标
- 🔮 访问修订历史
- 🔮 高级过滤和排序
- 🔮 发布集成
注： 这些增强依赖于Ulysses扩展其x-callback-url API。MCP服务器设计为在新的API功能可用时易于更新。
📚 文档
有关体系结构、安全性、隐私和身份验证的详细信息，请参阅 docs/ 目录：
发展
建筑
npm run build观察变化
npm run watchMCP检验员测试
npm run inspector项目结构
ulysses-mcp/
├── src/
│ └── index.ts # Main server implementation
├── build/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── README.md
└── LICENSEAPI 参考
此服务器实现Ulysses x-callback-url API版本3。
关于API的详细文件：
故障排除
服务器未连接
- 验证您的Mac上是否安装了Ulysses
- 检查MCP配置中的构建路径
- 重建服务器：
npm run build - 重新启动MCP客户端
授权问题
- 跑
ulysses_authorize获取新令牌 - 在收到提示时批准Ulysses中的请求
- 复制并保存访问令牌
- Ulysses首选项中的支票令牌未被撤销
工作表标识符不起作用
- 验证22个字符的标识符格式
- 确保尤利西斯中的纸张仍然存在
- 注意：如果项目移动，外部文件夹标识符可能会更改
贡献
欢迎投稿！请随时提交拉取请求。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
免责声明
这是一个非官方工具，与Ulysses GmbH&Co.KG无关，也不受其认可。Ulysses是Ulysses GmbH＆Co.KG的商标。
致谢
支持
- 问题:
- Ulysses支持: ulysses.app/support
- MCP文件: 模型上下文协议.io
______________________________________________________________________
由以下材料制成❤️ 为Ulysses和人工智能社区
