Jules

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

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)

- 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)

- 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.

# from the repository root pip install -e .

Option B — using uv (recommended during development):

Set your Jules API key via environment variable:

- Windows PowerShell

$Env:JULES_API_KEY = "<your_api_key_here>"

export JULES_API_KEY="<your_api_key_here>"

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

There are two common ways to run the server.
- 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())

- As a standalone MCP server executable for external MCP clients:

uv run fastmcp run jules_mcp/jules_mcp.py:mcp

- 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:

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

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())

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"))

-

Create a virtual environment and install dev dependencies

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

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

- Package name: jules-mcp
- Version: 0.1.0
- Entry points:

- Python module: python -m jules_mcp
- FastMCP source: jules_mcp/jules_mcp.py:mcp

Apache License 2.0. See the LICENSE file for details.

- FastMCP —https://gofastmcp.com/
- Model Context Protocol —https://modelcontextprotocol.io/
- jules-agent-sdk — unofficial/official SDK used by this server

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB