AI导哈

AI编码任务管理服务器

Jules MCP服务器是Google Jules AI编码代理的模型上下文协议服务器，使AI助手能够通过Jules API创建和管理异步编码任务。

  • by Omarbadran37
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Omarbadran37/jules-mcp-server

使用说明

Jules MCP 服务器

谷歌Jules AI编码代理的模型上下文协议（MCP）服务器。使像Claude这样的AI助手能够通过Jules API创建和管理异步编码任务。

概述

Jules是谷歌的人工智能编码代理，它在隔离的云虚拟机中执行开发任务。这个MCP服务器通过8个标准化工具公开了Jules的功能，人工智能助手可以自动发现并调用这些工具。

朱尔斯能做什么：

  • 从自然语言描述生成代码
  • 修复包括竞态条件和逻辑错误在内的各种bug
  • 创建包含模拟功能的全面测试套件
  • 更新依赖项并处理破坏性变更
  • 跨多个文件重构代码
  • 搜索文档并进行代码审查

任务异步执行，通常根据复杂度在5到60分钟内完成。

先决条件

  1. 谷歌账户 与Jules的访问权限一起
  2. 朱尔斯API密钥 - 从 https://jules.google.com/settings#api 获取（最多允许3个密钥）
  3. GitHub 集成 - 在 https://jules.google.com 上安装 Jules GitHub 应用以连接存储库
  4. Node.js 您的系统上已安装18+（注：18+通常指包含成人内容的软件或资源，此翻译基于原文语境，但需注意，传播或访问此类内容可能违反法律法规，请遵守相关规定）

快速入门

1. 安装

cd jules-mcp-server
npm install
npm run build

2. 配置API密钥

创建一个 .env 文件（永远不要提交这个）：

cp .env.example .env
# Edit .env and add your Jules API key

或者直接在 Claude Desktop 配置中输入密钥（推荐 - 详见下文）。

3. 配置Claude桌面版

编辑您的Claude桌面配置文件：

  • macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux（发音近似“林克斯”）： ~/.config/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "jules": {
      "command": "node",
      "args": ["/absolute/path/to/jules-mcp-server/build/index.js"],
      "env": {
        "JULES_API_KEY": "your_actual_jules_api_key_here"
      }
    }
  }
}

重要提示：

  • 使用绝对路径来 build/index.js （不相关）
  • 替换 your_actual_jules_api_key_here 使用您的真实API密钥
  • 更改完成后，完全重启Claude桌面版

4. 验证安装

  1. 重启Claude桌面版
  2. 在Claude界面中寻找🔌图标
  3. 你应该能看到一个名为“jules”的服务器，上面有8个可用工具
  4. 试试问Claude：“列出我的Jules仓库”

可用工具

1. jules_list_sources

列出与Jules关联的所有GitHub仓库。

示例提示： “给我看看我的Jules仓库”

2. jules_create_session

开始一个新的异步编码任务。

参数：

  • repoOwner - GitHub 仓库所有者/组织
  • repoName - 仓库名称
  • prompt - 详细的任务描述
  • branch - 起始分支（默认：“main”）
  • autoApprove - 自动批准计划（默认：true）
  • autoCreatePR - 任务完成后自动创建PR（默认：false）

示例提示： “为 myorg/myrepo 创建一个 Jules 会话，以添加身份验证模块的单元测试”

3. jules_list_sessions

列出所有Jules会话及其状态。

示例提示： “显示我所有的Jules会话”

4. jules_get_status

检查会话状态和最近的活动。使用此功能来轮询检查完成状态。

示例提示： “检查Jules会话abc123的状态”

5. jules_send_message

向正在进行的会话发送跟进信息。

示例提示： “告诉Jules，在会话abc123中也要添加错误处理。”

6. jules_list_activities

获取详细的活动日志，包括计划步骤和进度更新。

示例提示： “请给我显示会话abc123的详细活动”

7. jules_approve_plan

批准执行计划（仅在需要时） autoApprove=false）。

示例提示： “批准Jules会议abc123的计划”

8. jules_get_session_output

从已完成的会话中检索最终结果和PR（Pull Request）URL。

示例提示： “获取Jules会话abc123的结果”

使用示例

基本工作流程

You: "I need to add authentication tests to my project"

Claude: I'll help you create a Jules session for that.
[Uses jules_list_sources to find your repos]
[Uses jules_create_session with your requirements]

Claude: Session created! ID: ses_abc123. Jules is working on this task.
I'll check back in 30 seconds.
[Waits, then uses jules_get_status periodically]

Claude: Jules completed the task! Here's the pull request: [URL]

手动计划审批工作流程

You: "Create a Jules session to refactor the database layer, but I want to approve the plan first"

Claude: I'll create a session with manual approval.
[Uses jules_create_session with autoApprove=false]

Claude: Session created and waiting for plan approval.
[Uses jules_list_activities to show the plan]

You: "Looks good, approve it"

Claude: [Uses jules_approve_plan]
Plan approved! Jules is now executing.

发送后续指示

You: "Check on my Jules session ses_abc123"

Claude: [Uses jules_get_status]
Jules is working on adding tests. Currently implementing auth tests.

You: "Tell Jules to also add integration tests"

Claude: [Uses jules_send_message]
Message sent. Jules will incorporate this in the next steps.

速率限制和配额

Jules 根据订阅级别强制执行任务配额：

  • 免费15项日常任务，3项并发任务
  • Google AI Pro（谷歌人工智能专业版/谷歌AI专业版） （19.99美元/月）：约75个每日任务，15个并发任务
  • Google AI Ultra（谷歌超智能技术/谷歌极致人工智能，具体译名可能根据上下文调整） （124.99美元/月）：约300个每日任务，60个并发任务

即使任务失败，也会计入您的配额。配额在每24小时滚动周期内重置。

异步工作流模式

Jules 会话在云虚拟机中异步运行。典型的工作流程如下：

  1. 创建会话 - 立即返回并附带会话ID
  2. 查询状态 - 每隔10-30秒检查一次，使用 jules_get_status
  3. 监控活动 - 查看详细进度 jules_list_activities
  4. 检索结果 - 当状态为“已完成”时获取PR URL

当你要求监控某个任务时，Claude 会自动处理这个轮询。

故障排除

工具未出现在Claude桌面版中

  1. 验证配置中的绝对路径（而非相对路径）
  2. 检查一下 build/index.js 运行后存在 npm run build
  3. 确保API密钥设置正确
  4. 完全重启Claude桌面版（而不仅仅是重新加载）
  5. 检查控制台日志中的错误信息

“JULES_API_KEY 环境变量缺失”错误

  • 在Claude桌面配置中未设置API密钥
  • 确保 env 配置中的对象包含 JULES_API_KEY

“未连接到 Jules 的存储库”错误

  1. 访问 https://jules.google.com
  2. 点击“连接到GitHub账户”
  3. 授权Jules GitHub应用
  4. 选择仓库以授予访问权限
  5. 刷新Jules网页应用以同步

会话立即失败

  • 检查仓库是否已连接到Jules
  • 验证分支名称是否存在
  • 确保仓库具有适当的访问权限
  • 检查Jules的网页界面以获取详细的错误信息

API错误（401，403，404）

  • 401无效的API密钥 - 请在https://jules.google.com/settings#api重新生成
  • 403权限不足或配额已超出
  • 404会话ID或存储库未找到

发展

以开发模式运行

npm run dev  # Watch mode - rebuilds on changes

使用MCP Inspector进行测试

npm run inspector

这会打开一个网页界面，您可以在其中无需使用Claude Desktop即可交互式地测试工具。

项目结构

jules-mcp-server/
├── src/
│   ├── index.ts      # Main server and tool implementations
│   ├── client.ts     # Jules API client helper
│   └── types.ts      # TypeScript type definitions
├── build/            # Compiled JavaScript (git-ignored)
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
└── .env              # API key (git-ignored, create from .env.example)

添加新工具

  1. 在（某处）定义类型 src/types.ts
  2. 添加工具注册功能 src/index.ts 遵循现有模式
  3. 使用Zod模式进行输入验证
  4. 在try-catch块中包装实现，并提供适当的错误响应
  5. 重建： npm run build

安全最佳实践

  1. 永远不要提交API密钥 - 使用 .env 或仅配置Claude Desktop
  2. 使用 .gitignore 文件 - 确保 .env 并且 build/ 被排除在外
  3. 定期更换密码 - 在 https://jules.google.com/settings#api 上重新生成
  4. 监控使用情况 - 检查Jules的网页界面是否有异常活动
  5. 限制仓库访问 - 仅授予朱尔斯访问必要仓库的权限

Claude 桌面配置技巧

使用绝对路径：

✅ "/Users/username/jules-mcp-server/build/index.js"
❌ "~/jules-mcp-server/build/index.js"
❌ "./jules-mcp-server/build/index.js"

多台服务器：

{
  "mcpServers": {
    "jules": { ... },
    "other-server": { ... }
  }
}

调试日志： 检查Claude Desktop日志：

  • macOS（苹果电脑操作系统）: ~/Library/Logs/Claude/
  • Windows： %APPDATA%\Claude\logs\

API 参考文档

这个服务器实现了Jules API v1alpha：

  • 基本URL： https://jules.googleapis.com/v1alpha
  • 认证： X-Goog-Api-Key 头球
  • 文档https://jules.google.com（需要账户）

资源

  • Jules 网页界面https://jules.google.com（可译为）：谷歌Jules服务网址
  • 获取API密钥https://jules.google.com/settings#api 的中文翻译为：“https://jules.google.com/设置#api（或“https://jules.google.com/设置界面#api”，具体根据上下文调整）”。不过，通常我们不会直接翻译网址，而是说明其用途或指向的内容，比如：“这是Jules Google应用的API设置页面链接”
  • 连接GitHubhttps://jules.google.com（GitHub 集成部分）
  • MCP 文档https://modelcontextprotocol.io 翻译为中文是：“https://模型上下文协议.io” 或者根据具体语境，也可以简化为“模型上下文协议官网”。不过，由于网址本身通常不直接翻译，这里主要是对网址中包含的域名部分进行了意译说明
  • **Claude Desktop（可译为“Claude桌面版”或保持原样，具体根据上下文决定是否需要意译）**https://claude.ai/download 翻译为中文是：“https://claude.ai/下载”

许可证

麻省理工学院（MIT）

做出贡献

欢迎投稿！请确保：

  • TypeScript 编译无错误
  • 所有工具都遵循错误处理模式
  • 已更新文档以包含新功能
  • 提交中不得包含API密钥或秘密

更新日志

版本1.0.0（2025年1月15日）

  • 首次发布
  • 8个核心工具用于Jules API集成
  • Claude Desktop 的标准I/O传输
  • 全面的错误处理和日志记录
  • 完整的TypeScript类型安全性

相关 MCP