jules-mcp-server

CodeAgentBridge/jules-mcp-server

3.3

If you are the rightful owner of jules-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Jules MCP Server is an MCP (Model Context Protocol) server that provides access to Google Jules Agent operations through FastMCP, allowing clients to manage sources, sessions, and activities using the jules-agent-sdk.

Tools
5
Resources
0
Prompts
0

Jules MCP Server (jules-mcp)

An MCP (Model Context Protocol) server that exposes Google Jules Agent operations via FastMCP.

This server lets MCP-compatible clients (and Python code) list Jules sources, create and manage sessions, and inspect activities using the official jules-agent-sdk.

  • Server framework: FastMCP
  • SDK: jules-agent-sdk
  • Python: 3.13+
  • License: Apache-2.0

Features

Tools exposed via the MCP server (grouped by area):

  • Sources
    • get_source(source_id)
    • list_sources(filter_str=None, page_size=None, page_token=None)
    • get_all_sources(filter_str=None)
  • Sessions
    • create_session(prompt, source, starting_branch=None, title=None, require_plan_approval=False)
    • get_session(session_id)
    • list_sessions(page_size=None, page_token=None)
    • approve_session_plan(session_id)
    • send_session_message(session_id, prompt)
    • wait_for_session_completion(session_id, poll_interval=5, timeout=600)
  • Activities
    • get_activity(session_id, activity_id)
    • list_activities(session_id, page_size=None, page_token=None)
    • list_all_activities(session_id)

See jules_mcp/jules_mcp.py for signatures and inline docstrings.

Installation

Option A — from a local checkout:

# from the repository root
pip install -e .

Option B — using uv (recommended during development):

# from the repository root
uv sync

The project targets Python 3.13+.

Configuration

Set your Jules API key via environment variable:

  • Windows PowerShell 
    $Env:JULES_API_KEY = "<your_api_key_here>"
  • Unix shells (bash/zsh) 
    export JULES_API_KEY="<your_api_key_here>"

If you do not provide an argument to jules(), the SDK reads JULES_API_KEY automatically.

Running the MCP server

There are two common ways to run the server.

  1. Programmatic run (in-process) using FastMCP Client — useful for testing or embedding:
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def main():
    async with Client(mcp) as client:
        # Example: list all sources (auto-paginated)
        result = await client.call_tool("get_all_sources")
        print(result)

asyncio.run(main())
  1. As a standalone MCP server executable for external MCP clients:

  • Using uv and FastMCP directly

    uv run fastmcp run jules_mcp/jules_mcp.py:mcp

    This starts the MCP server over stdio.

  • Using the provided configuration files

    • MCP.json: a sample command configuration for MCP-aware hosts.
    • fastmcp.json: FastMCP runtime/environment configuration.

Adjust paths in MCP.json if you use a different checkout location.

You can also run via the module entry point:

python -m jules_mcp

This calls start_mcp() which invokes FastMCP.run() using the "mcp" instance defined in the package.

Usage notes and examples

  • Listing and filtering sources
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def main():
    async with Client(mcp) as client:
        # Filter syntax follows AIP-160 filtering rules supported by Jules
        res = await client.call_tool(
            "list_sources",
            {"filter_str": "name=sources/source1 OR name=sources/source2", "page_size": 10}
        )
        print(res)

asyncio.run(main())
  • Creating a session and waiting for completion
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def run_session():
    async with Client(mcp) as client:
        session = await client.call_tool(
            "create_session",
            {
                "prompt": "Analyze the repository and propose improvements",
                "source": "sources/abc123",
                "require_plan_approval": True,
            },
        )

        # Optionally approve plan
        await client.call_tool("approve_session_plan", {"session_id": session["name"]})

        # Wait for completion
        final = await client.call_tool(
            "wait_for_session_completion",
            {"session_id": session["name"], "poll_interval": 5, "timeout": 600}
        )
        print(final)

asyncio.run(run_session())
  • Inspecting activities
import asyncio
from fastmcp import Client
from jules_mcp import mcp

async def list_acts(session_id: str):
    async with Client(mcp) as client:
        acts = await client.call_tool("list_all_activities", {"session_id": session_id})
        for a in acts:
            print(a)

asyncio.run(list_acts("sessions/abc123"))

Development

  • Create a virtual environment and install dev dependencies

    uv sync
# or: pip install -e .[dev]

  • Run tests (note: some tools may reach the Jules API and require JULES_API_KEY)

    uv run pytest -q

  • Linting/formatting: follow your preferred tools; this repo does not include linters by default.

Project metadata

  • Package name: jules-mcp
  • Version: 0.1.0
  • Entry points:
    • Python module: python -m jules_mcp
    • FastMCP source: jules_mcp/jules_mcp.py:mcp

License

Apache License 2.0. See the LICENSE file for details.

Acknowledgements