Jules MCP Server

MCP (Model Context Protocol) server for Google Jules - the AI coding agent. This server enables LLMs like Claude to interact with Jules API, creating and managing coding sessions programmatically.

Architecture

The Jules MCP Server acts as a bridge between MCP-compatible clients and the Jules REST API.

┌──────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  MCP Client  │      │ Jules MCP Server │      │  Jules REST API  │
│ (Claude, etc)│ ◄──► │ (stdio/HTTP)     │ ◄──► │ (googleapis.com) │
└──────────────┘      └──────────────────┘      └──────────────────┘

1. MCP Client: An application like Claude Desktop that supports the Model Context Protocol.
2. Jules MCP Server: This project, which exposes Jules's capabilities as MCP tools and translates them to Jules API calls.
3. Jules REST API: The underlying Google API that powers Jules's coding capabilities.

Features

• Session Management: Create, list, get, and delete coding sessions
• Interactive Communication: Send messages to active sessions and approve plans
• Activity Monitoring: Track progress through session activities
• Source Management: List and inspect connected GitHub repositories
• Dual Transport: Supports both stdio and HTTP transports

Prerequisites

• Node.js 18+
• Jules API Key (get from jules.google.com/settings)
• Connected GitHub repositories in Jules

Installation

# Clone or download the server
cd jules-mcp-server

# Install dependencies
npm install

# Build the TypeScript
npm run build

Configuration

Set your Jules API key as an environment variable:

export JULES_API_KEY="your-api-key-here"

Security

Manage your JULES_API_KEY with care:

• Environment Variables: Always use environment variables to provide the API key. Avoid hardcoding it in source code or configuration files.
• No Commits: Never commit your API key or .env files containing keys to version control. The .gitignore file is configured to ignore .env files.
• Least Privilege: The Jules API key provides full access to your Jules sessions and connected repositories. Keep it secure and rotate it if you suspect it has been compromised.
• CI/CD: When using in CI/CD environments (like GitHub Actions), use Secrets to store and inject the API key.

Usage

With Claude Desktop (stdio transport)

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "jules": {
      "command": "node",
      "args": ["/path/to/jules-mcp-server/dist/index.js"],
      "env": {
        "JULES_API_KEY": "your-api-key-here"
      }
    }
  }
}

With Claude Code (CLI)

You can add this server to Claude Code by running:

claude mcp add jules --env JULES_API_KEY=your-api-key-here -- node /path/to/jules-mcp-server/dist/index.js

Command Line

# Run with stdio transport
JULES_API_KEY=your-key node dist/index.js

# Run with HTTP transport
JULES_API_KEY=your-key node dist/index.js --http

# Custom port for HTTP
JULES_API_KEY=your-key PORT=8080 node dist/index.js --http

# Show help
node dist/index.js --help

Tool Reference

The server provides a suite of tools to interact with Jules. Some tools support a response_format parameter (markdown or json); refer to each tool's documented arguments to see whether it is accepted.

Session Tools

jules_create_session

Creates a new coding session where Jules executes a task on a repository.

• Arguments:

  • prompt (string, required): Task description.
  • sourceContext (object, required): Repository info (e.g., { "source": "sources/github-owner-repo", "githubRepoContext": { "startingBranch": "main" } }).
  • title (string, optional): Session title.
  • requirePlanApproval (boolean, optional): If Jules should wait for plan approval.
  • automationMode (string, optional): Use AUTO_CREATE_PR to automatically create a PR on completion.
  • response_format (string, optional): Response format, either markdown or json.

• Example Response (Markdown):

  ## Session: Add auth tests
  
  **ID:** 1234567
  **State:** ⏳ QUEUED
  **Prompt:** Add unit tests for the authentication module
  **URL:** https://jules.google/session/1234567
  

jules_list_sessions

Lists all your coding sessions.

• Arguments:

  • pageSize (number, optional): Max results per page (1-100, default: 20).
  • pageToken (string, optional): Token for the next page.
  • response_format (string, optional): Format for the response output.

• Example Response (JSON):

  {
    "sessions": [
      {
        "id": "1234567",
        "title": "Add auth tests",
        "state": "IN_PROGRESS",
        "createTime": "2023-10-27T10:00:00Z"
      }
    ],
    "total": 1,
    "hasMore": false
  }
  

jules_get_session

Retrieves full details for a specific session, including current state, URL, and outputs (like PR links) if completed.

• Arguments:

  • sessionId (string, required): The ID of the session.
  • response_format (string, optional): 'markdown' (default) or 'json'.

• Example Response (Markdown):

  ## Session: Add auth tests
  
  **ID:** 1234567
  **State:** ✅ COMPLETED
  **Prompt:** Add unit tests for the authentication module
  **URL:** https://jules.google/session/1234567
  
  **Created:** Oct 27, 2023, 10:00 AM
  **Updated:** Oct 27, 2023, 10:45 AM
  
  ### Outputs
  
  **Pull Request:** [Add auth unit tests](https://github.com/myorg/myrepo/pull/42)
  
  > This PR adds comprehensive unit tests for the auth module.
  

• Example Response (JSON):

  {
    "id": "1234567",
    "title": "Add auth tests",
    "prompt": "Add unit tests for the authentication module",
    "state": "COMPLETED",
    "url": "https://jules.google/session/1234567",
    "outputs": [
      {
        "pullRequest": {
          "title": "Add auth unit tests",
          "url": "https://github.com/myorg/myrepo/pull/42",
          "description": "This PR adds comprehensive unit tests for the auth module."
        }
      }
    ],
    "createTime": "2023-10-27T10:00:00Z",
    "updateTime": "2023-10-27T10:45:00Z"
  }
  

jules_delete_session

Deletes a coding session. This cannot be undone.

• Arguments:
  • sessionId (string, required): The ID of the session.

jules_send_message

Sends a message to an active session. Use this to provide feedback, answer Jules's questions, or change instructions mid-session.

• Arguments:
  • sessionId (string, required): The ID of the session.
  • prompt (string, required): Your message.

jules_approve_plan

Approves a pending plan. Required if requirePlanApproval was set to true during session creation. Once approved, Jules begins execution.

• Arguments:
  • sessionId (string, required): The ID of the session.

Activity Tools

jules_list_activities

Lists all activities (events, plan generation, code changes, messages) for a session.

• Arguments:
  • sessionId (string, required): The ID of the session.
  • pageSize (number, optional): Results per page. Must be between 1 and 100. Defaults to the schema-defined default when omitted.
  • pageToken (string, optional): Pagination token.
  • response_format (string, optional): Response format for the returned activities.

jules_get_activity

Gets detailed information about a specific activity. This is how you view code diffs (changeSet), bash outputs, or full plan details.

• Arguments:
  • sessionId (string, required): The ID of the session.
  • activityId (string, required): The activity ID.
  • response_format (string, optional): Controls the format of the returned activity details.

Source Tools

jules_list_sources

Lists GitHub repositories connected to your Jules account via the Jules web UI.

• Arguments:
  • filter (string, optional): Filter by name (e.g., name=sources/github-owner-repo).
  • pageSize (number, optional): Results per page.
  • pageToken (string, optional): Pagination token.
  • response_format (string, optional): Response format for the returned data.

jules_get_source

Gets details about a specific connected repository, including all available branches.

• Arguments:
  • sourceId (string, required): The source ID (e.g., github-owner-repo). This is not the sources/... resource name used by sourceContext.source.
  • response_format (string, optional): Controls the response format returned by the tool.

Real-World Examples

Complete Workflow: Implementing a Feature

1. Find the repository ID: jules_list_sources() -> returns sources/github-acme-webapp.

2. Start the session: jules_create_session(prompt="Add a search bar to the header", sourceContext={"source": "sources/github-acme-webapp"}, requirePlanApproval=true) -> returns sessionId 7890.

3. Check for a plan: jules_list_activities(sessionId="7890"). Look for an activity with "Plan Generated".

4. Review and approve: jules_get_activity(sessionId="7890", activityId="plan_activity_id"). If the plan looks good: jules_approve_plan(sessionId="7890").

5. Monitor progress: Periodically call jules_get_session(sessionId="7890") to check state or jules_list_activities to see recent actions.

6. Review the result: Once state is COMPLETED, check jules_get_session for the Pull Request URL.

Session States

State	Description
QUEUED	Session created, waiting for processing.
PLANNING	Jules is analyzing the codebase and creating a plan.
AWAITING_PLAN_APPROVAL	Plan is ready and requires your approval to proceed.
AWAITING_USER_FEEDBACK	Jules has a question or needs more information.
IN_PROGRESS	Jules is executing the task/plan.
PAUSED	Execution has been temporarily halted.
COMPLETED	Task finished successfully (check for PR link).
FAILED	Task failed. Check activities for error details.

Troubleshooting

Error	Meaning	Resolution
401 Unauthorized	Invalid API Key	Check your JULES_API_KEY environment variable and ensure it's valid.
403 Forbidden	Permission Denied	Ensure your API key has access to the requested resource or repository.
404 Not Found	Resource Missing	Verify the sessionId, activityId, or sourceId is correct.
429 Too Many Requests	Rate Limited	You've exceeded the API rate limit. Wait a few minutes before retrying.
500 / 503	Jules API Error	The Jules service is experiencing issues. Try again later or check Jules Status.
ECONNREFUSED	Network Error	Check your internet connection or firewall settings.

Development

# Install dependencies
npm install

# Build
npm run build

# Type-check without emitting files
npm run check

# Lint source files
npm run lint

# Check formatting
npm run format:check

# Development mode (watch)
npm run dev

Contributing

We welcome contributions! See CONTRIBUTING.md for more details.

1. Check Issues: Look for existing issues or open a new one to discuss your proposed change.
2. Local Setup: Follow the Installation steps.
3. Topic Branches: Always work on a new branch (git checkout -b feature/my-feature).
4. Testing: If adding a tool, ensure it's tested. Run npm run check and npm run lint.
5. Documentation: Update the README if you change tool behavior or add new features.
6. Pull Requests: Submit a PR with a clear description of the changes.

Project hygiene and community documents:

• CHANGELOG.md
• SECURITY.md
• LICENSE

API Reference

Based on Jules REST API:

• Base URL: https://jules.googleapis.com/v1alpha
• Authentication: x-goog-api-key header
• Full documentation: jules.google/docs/api/reference

License

MIT