非官方Jules MCP服务器
](https://npmjs.org/package/jules-mcp-server)
jules-mcp-server 将您的AI编程助手（如Claude、Cursor或Copilot）连接到 朱尔斯API它支持直接从您的集成开发环境（IDE）中进行自主编码会话。它作为模型上下文协议（MCP）服务器，使您的AI助手能够创建编码会话、管理任务，并与Jules代理进行交互，以实现自动化软件开发。
更新日志 | 故障排除
关键特性
- 自主编码时段直接从您的AI助手创建和管理Jules编码会话
- GitHub 集成通过Jules源连接到您的GitHub仓库
- 计划审批工作流程在朱尔斯做出更改之前，审查并批准执行计划
- 实时活动追踪监控会话进度并查看详细活动日志
- 类型安全验证使用Zod进行运行时验证，确保在API调用前对所有输入进行验证
- 可流式传输的HTTP传输使用MCP可流式传输HTTP规范以确保可靠通信
免责声明
jules-mcp-server 为您的MCP客户端提供访问权限，以便在连接的GitHub存储库中创建和管理编码会话。确保在执行前审查并批准计划，特别是在生产存储库中。服务器需要一个具有适当权限的有效Jules API密钥。
要求
- v18或更高版本
- Jules API账户 使用API密钥
开始入门
1. 克隆并安装
git clone https://github.com/yourusername/jules-mcp-server.git
cd jules-mcp-server
npm install2. 配置环境
cp .env.example .env
# Edit .env and add your JULES_API_KEY你的 .env 文件应包含：
JULES_API_KEY=your_api_key_here
PORT=3323
HOST=127.0.0.13. 启动服务器
npm run dev
# Server starts at http://127.0.0.1:3323/mcp对于生产：
npm run build
npm run start:node4. 配置您的MCP客户端
在您的MCP客户端中添加以下配置：
{
"mcpServers": {
"jules": {
"type": "streamable-http",
"url": "http://127.0.0.1:3323/mcp"
}
}
}\[!重要\]\ Jules MCP服务器使用 可流式传输的HTTP 传输前必须先运行，然后才能连接您的MCP客户端。与基于标准输入输出（stdio）的服务器不同，此服务器作为一个持久的HTTP服务运行。
MCP 客户端配置
Claude Desktop
编辑您的Claude桌面配置文件：
macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json\ Windows： %APPDATA%\Claude\claude_desktop_config.json
添加Jules服务器配置：
{
"mcpServers": {
"jules": {
"type": "streamable-http",
"url": "http://127.0.0.1:3323/mcp"
}
}
}保存配置后，重启Claude桌面版。
Cursor
手动安装：
- 首选
Cursor Settings→Features→MCP - 点击
Add new global MCP server - 添加配置：
{
"mcpServers": {
"jules": {
"type": "streamable-http",
"url": "http://127.0.0.1:3323/mcp"
}
}
}- 重启光标
\[!NOTE\]（注：此标记通常用于表示以下内容为注意事项或提示）\ 在启动 Cursor 之前，请确保 Jules MCP 服务器正在运行。服务器采用无状态模式以确保与 Cursor 的最佳兼容性。
VS Code / Copilot
按照MCP安装指南进行安装 指南；引导者；向导 并使用上面提供的配置。
\[!NOTE\]（注：此标记通常用于提示或说明，以下为翻译内容）\ Streamable HTTP 支持可能会因 MCP 客户端版本的不同而有所差异。请确保您使用的是支持该功能的最新版本 streamable-http 运输类型。Other MCP Clients
对于其他支持可流式HTTP传输的MCP客户端，请使用上述提供的配置。确保客户端支持：
- MCP协议版本
2024-11-05或更新版本 - 可流式传输的HTTP传输（
type: "streamable-http") - 无状态模式（无需会话管理）
你的第一个提示
在您的MCP客户端中输入以下提示以验证设置：
List my Jules sources您的MCP客户端应该调用 jules_list_sources 工具并显示您连接的GitHub仓库。
创建一个编码会话：
Create a Jules session for sources/github/owner/repo with the prompt "Add a README file"\[!TIP\]（提示）\ 使用 requirePlanApproval: true 在创建会话以审查朱尔斯执行更改前的内容时。工具
所有工具均包含使用Zod进行的运行时验证，以确保类型安全并提供清晰的错误信息。
- 会话管理 （3个工具）
- jules_create_session - 创建一个新的Jules编码会话 - jules_list_sessions - 列出你所有的Jules会话 - jules_send_message - 向活跃的Jules代理发送消息
- 计划审批 (1个工具)
- jules_approve_plan - 批准一个会话的执行计划
- 监测 （2种工具）
- jules_list_sources - 列出你连接的GitHub源 - jules_list_activities - 列出会议期间的活动
工具详情
jules_list_sources
列出您已连接的GitHub资源。
参数：
pageSize（可选）：每页项目数量（1-100）pageToken（可选）：用于分页的令牌
jules_create_session
创建一个新的Jules编码会话。
参数：
prompt（必填）：给朱尔斯的任务提示（1-10000个字符）source（必填）：源路径，例如。，sources/github/owner/repotitle（可选）：会话标题（1-200个字符）startingBranch（可选）：要开始的 Git 分支（默认：main)requirePlanApproval（可选）：是否在执行前要求计划审批（默认：false)
jules_list_sessions
列出你所有的Jules会话。
参数：
pageSize（可选）：每页项目数量（1-100）pageToken（可选）：用于分页的令牌
jules_approve_plan
批准会话的执行计划。
参数：
sessionId（必填）：待批准的会话ID，格式：sessions/{id}
jules_send_message
给一位在线的Jules客服发送消息。
参数：
sessionId（必填）：会话ID，格式：sessions/{id}prompt（必填）：要发送的消息（1-10000个字符）
jules_list_activities
列出会议活动。
参数：
sessionId（必填）：会话ID，格式：sessions/{id}pageSize（可选）：每页项目数量（1-100）pageToken（可选）：用于分页的令牌
资源
服务器提供了两个MCP资源以提供额外上下文：
jules://sources- 您连接的GitHub源jules://sessions/{id}/activities- 指定会话的最新活动
MCP客户端可以直接访问资源以收集上下文信息。
配置
Jules MCP 服务器支持以下环境变量：
JULES_API_KEY（必填）
您的Jules API密钥，用于身份验证。
- 类型： 字符串
PORT
HTTP服务器的端口号。
- 类型： 数字；号码 - 默认： 3323
HOST
服务器绑定的主机地址。
- 类型： 字符串 - 默认： 127.0.0.1
ALLOWED_ORIGINS
用于CORS的允许来源的逗号分隔列表。
- 类型： 字符串 - 默认： null,http://localhost
在您的（设置/环境中）配置这些 .env 文件：
JULES_API_KEY=your_api_key_here
PORT=3323
HOST=127.0.0.1
ALLOWED_ORIGINS=null,http://localhost建筑学
无状态模式
服务器在运行于 无状态模式 （无会话管理）以实现与Cursor等MCP客户端的最佳兼容性。每个请求都是独立的，不需要会话ID头。
交通
使用MCP（多通道处理器/微控制器等，具体含义根据上下文确定） 可流式传输的HTTP 运输规范包含：
- 已启用JSON响应
enableJsonResponse: true） - 没有会话管理（
sessionIdGenerator: undefined） - 可配置来源的CORS保护
- 用于调试的请求/响应日志记录
验证
所有工具输入在调用API之前都会使用Zod模式进行验证：
- 阻止无效请求到达Jules API
- 提供清晰、可操作的错误信息
- 通过早期捕获错误来节省API配额
- 确保请求管道中的类型安全
见 VALIDATION_EXAMPLES.md 翻译为中文是：“验证示例.md”（文件名通常保持原样，不翻译扩展名，但此处为说明，可理解为“验证示例的Markdown文件”）。不过，在实际文件名处理中，我们通常会直接使用“验证示例.md”来指代这个文件，无需额外翻译 有关详细验证规则和示例，请参阅。
故障排除
服务器无法启动
问题： 服务器无法启动或立即崩溃。
解决方案：
- 验证
JULES_API_KEY设定于.env - 检查端口3323是否未被占用：
netstat -ano | findstr :3323(Windows) 或lsof -i :3323(macOS/Linux) - 确保 Node.js 版本为 18 或更高版本：
node --version - 检查服务器日志以查找具体的错误信息
光标显示“无工具”
问题： MCP 连接似乎正常，但未列出任何工具。
解决方案：
- 验证服务器是否正在运行：
curl http://127.0.0.1:3323/mcp不应返回连接错误 - 在更改配置后重启光标（或：光标服务）
- 检查你的配置中的URL是否完全正确
http://127.0.0.1:3323/mcp - 确保服务器处于无状态模式（默认配置）
- 尝试重启服务器：先停止它，然后运行
npm run dev再次
CORS/Origin 错误
问题： 服务器返回403禁止访问（Origin错误）。
解决方案：
- 添加
nulltoALLOWED_ORIGINS在.env用于本地开发 - 对于自定义来源，请更新
ALLOWED_ORIGINS：ALLOWED_ORIGINS=null,http://localhost,http://127.0.0.1 - 更改环境变量后重启服务器
验证错误
问题： 工具调用因验证错误而失败。
解决方案：
- 检查错误信息以了解特定字段的要求
- 验证会话ID是否符合格式
sessions/{id} - 验证源路径是否符合格式
sources/github/owner/repo - 确保字符串长度在指定范围内
- 见 VALIDATION_EXAMPLES.md 翻译为中文是：“验证示例.md” 对于正确的输入格式
API认证错误
问题： 工具因401未授权错误而失败。
解决方案：
- 验证您的
JULES_API_KEY有效且处于激活状态 - 请检查API密钥是否具有必要的权限
- 确保
.env文件位于项目根目录中 - 更新API密钥后重启服务器
连接超时
问题： 向Jules API发出的请求超时或卡住。
解决方案：
- 检查你的网络连接
- 验证Jules API的状态 status.jules.ai（可译为“jules.ai的状态”或根据具体语境简化为“jules.ai状态”） （如有提供）
- 如果处理大型仓库，请增加超时值
- 检查防火墙设置，这些设置可能会阻止出站的HTTPS请求
发展
从源代码构建
npm install
npm run buildTypeScript 源代码在 src/ 编译成JavaScript在 dist/。
在开发模式下运行
npm run dev这使用的是 tsx 直接运行TypeScript并支持热重载。
项目结构
jules-mcp-server/
├── src/
│ ├── server.ts # Main server and MCP setup
│ ├── client/
│ │ └── jules-client.ts # Jules API client
│ ├── tools/
│ │ ├── index.ts # Tool registry
│ │ ├── sources.ts # Source management tools
│ │ ├── sessions.ts # Session management tools
│ │ └── activities.ts # Activity monitoring tools
│ ├── schemas/
│ │ └── index.ts # Zod validation schemas
│ ├── resources/
│ │ └── index.ts # MCP resources
│ └── types/
│ └── tool.ts # Type definitions
├── dist/ # Compiled JavaScript
├── .env # Environment configuration
└── package.json已知的限制
支持Streamable HTTP客户端
并非所有MCP客户端都完全支持Streamable HTTP传输。本服务器已与以下进行过测试：
- ✅ Cursor（无状态模式）
- ✅ Claude Desktop（需手动配置）
- ⚠️ VS Code/Copilot（有限支持，请检查版本）
会话管理
服务器使用无状态模式以确保兼容性。如果您需要有状态的会话管理，您可以进行修改 src/server.ts 使能够 sessionIdGenerator但这样做可能会破坏与某些客户端（如 Cursor）的兼容性。
仅限本地访问
默认情况下，服务器绑定到 127.0.0.1 （仅限本地主机）以确保安全。若要允许远程访问，请更改 HOST 环境变量，但请确保在生产环境中实现适当的认证并使用HTTPS。
做出贡献
欢迎投稿！请：
- 为仓库创建分支（或“克隆仓库”）
- 创建一个特性分支
- 在测试中进行更改
- 提交一个拉取请求
许可证
MIT 许可证 - 详见 LICENSE 文件。
支持
- 问题：
- Jules API： 朱尔斯API
- MCP规范： modelcontextprotocol.io