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.

Related MCP server: Jules MCP Server

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

Troubleshooting

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