mcp/servers.txt

https://github.com/idosal/git-mcp.git

Skip to content

    idosal
    git-mcp

Repository navigation

Code
Issues33 (33)
Pull requests15 (15)
Discussions
Actions
Projects
Security

    Insights

Owner avatar
git-mcp
Public

idosal/git-mcp
t
Name	Last commit message
	Last commit date
idosal
idosal
fix: temporarily disable badge counter (#196)
d1808ca
 · 
5 months ago
.github
	
tests: add E2E infra (#126)
	
9 months ago
.husky
	
fix
	
10 months ago
.react-router/types
	
feat: add chat interface (#125)
	
9 months ago
app
	
feat: add Msty AI integration and configuration instructions (#180)
	
6 months ago
dist
	
Merge branch 'main' of https://github.com/idosal/git-mcp
	
10 months ago
img
	
cover image (#40)
	
9 months ago
public/img
	
feat: add badge support (#96)
	
9 months ago
src
	
fix: temporarily disable badge counter (#196)
	
5 months ago
static
	
feat: add badge support (#96)
	
9 months ago
tests
	
tests: add E2E infra (#126)
	
9 months ago
.env.example
	
Revert "Feature: graph tool (#169)" (#195)
	
5 months ago
.gitignore
	
Revert "Feature: graph tool (#169)" (#195)
	
5 months ago
.prettierrc
	
prettier
	
10 months ago
LICENSE
	
fix license in Github
	
9 months ago
README.md
	
feat: add Msty AI integration and configuration instructions (#180)
	
6 months ago
SECURITY.md
	
Create SECURITY.md (#132)
	
9 months ago
biome.json
	
chore: move to cloudflare workers (#27)
	
10 months ago
components.json
	
feat: add chat interface (#125)
	
9 months ago
package.json
	
Revert "Feature: graph tool (#169)" (#195)
	
5 months ago
playwright.config.ts
	
tests: add E2E infra (#126)
	
9 months ago
pnpm-lock.yaml
	
feat: support HTTP streaming (#154)
	
8 months ago
postcss.config.mjs
	
feat(ui): add ui
	
10 months ago
react-router.config.ts
	
chore: move to cloudflare workers (#27)
	
10 months ago
tailwind.config.js
	
chore: move to cloudflare workers (#27)
	
10 months ago
tsconfig.cloudflare.json
	
chore: move to cloudflare workers (#27)
	
10 months ago
tsconfig.json
	
chore: move to cloudflare workers (#27)
	
10 months ago
tsconfig.node.json
	
chore: move to cloudflare workers (#27)
	
10 months ago
vite.config.ts
	
chore: move to cloudflare workers (#27)
	
10 months ago
vitest.config.ts
	
tests: add E2E infra (#126)
	
9 months ago
worker-configuration.d.ts
	
feat: support HTTP streaming (#154)
	
8 months ago
wrangler.jsonc
	
tests: add E2E infra (#126)
	
9 months ago
Repository files navigation

README
Contributing
Apache-2.0 license

    Security

GitMCP

image

What is GitMCP • Features • Getting Started • How It Works • Badge • Examples • FAQ • Privacy • Contributing • License

GitMCP Twitter Follow Twitter Follow
Pulse MCP Badge
🤔 What is GitMCP?

Stop vibe-hallucinating and start vibe-coding!

GitMCP is a free, open-source, remote Model Context Protocol (MCP) server that transforms any GitHub project (repositories or GitHub pages) into a documentation hub. It enables AI tools like Cursor to access up-to-date documentation and code, even if the LLM has never encountered them, thereby eliminating code hallucinations seamlessly.

GitMCP supports two flavors -

    Specific Repository (gitmcp.io/{owner}/{repo} or {owner}.gitmcp.io/{repo}): Use these when you primarily work with a select number of libraries. This ensures your AI assistant always targets the correct project, enhancing security and relevance by preventing access to unintended repositories.
    Generic Server (gitmcp.io/docs): Use this for maximum flexibility when you need to switch between different repositories frequently. The AI assistant will prompt you (or decide based on context) which repository to access for each request. Be mindful that this relies on correctly identifying the target repository each time.

With GitMCP:

    AI assistants access the latest documentation and code directly from the source.
    Get accurate API usage and reliable code examples.
    Work effectively even with niche, new, or rapidly changing libraries.
    Significantly reduced hallucinations and improved code correctness.

For example, this side-by-side comparison shows the result for the same one-shot prompt in Cursor when creating a three.js scene -
GitMCP-threejs.mov
GitMCP-threejs.mov
✨ Features

    😎 Latest Documentation on ANY GitHub Project: Grant your AI assistant seamless access to the GitHub project's documentation and code. The built-in smart search capabilities help find exactly what the AI needs without using too many tokens!
    🧠 No More Hallucinations: With GitMCP, your AI assistant can provide accurate and relevant answers to your questions.
    ☁️ Zero Setup: GitMCP runs in the cloud. Simply add the chosen GitMCP URL as an MCP server in your IDE — no downloads, installations, signups, or changes are required.
    💬 Embedded Chat: Start quickly by chatting directly with the repository's documentation through our in-browser chat!
    ✅ Open, Free, and Private: GitMCP is open-source and completely free to use. It doesn't collect personal information or store queries. You can even self-host it!

GitMCP_PW.mp4
GitMCP_PW.mp4

🚀 Getting Started

Using GitMCP is easy! Simply follow these steps:
Step 1: Choose the type of server you want

Choose one of these URL formats depending on what you want to connect to:

    For GitHub repositories: gitmcp.io/{owner}/{repo}
    For GitHub Pages sites: {owner}.gitmcp.io/{repo}
    For a generic tool that supports any repository (dynamic): gitmcp.io/docs

Replace {owner} with the GitHub username or organization name, and {repo} with the repository name.

For your convenience, you can also use the conversion tool on the landing page to format the GitHub URL into an MCP URL!
Step 2: Connect your AI assistant

Select your AI assistant from the options below and follow the configuration instructions:
Connecting Cursor

Update your Cursor configuration file at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitmcp": {
      "url": "https://gitmcp.io/{owner}/{repo}"
    }
  }
}

Connecting Claude Desktop
In Claude Desktop, go to Settings > Developer > Edit Config
Replace the configuration with:

{
  "mcpServers": {
    "gitmcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://gitmcp.io/{owner}/{repo}"
      ]
    }
  }
}

Connecting Windsurf

Update your Windsurf configuration file at ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gitmcp": {
      "serverUrl": "https://gitmcp.io/{owner}/{repo}"
    }
  }
}

Connecting VSCode

Update your VSCode configuration file at .vscode/mcp.json:

{
  "servers": {
    "gitmcp": {
      "type": "sse",
      "url": "https://gitmcp.io/{owner}/{repo}"
    }
  }
}

Connecting Cline

Update your Cline configuration file at ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "gitmcp": {
      "url": "https://gitmcp.io/{owner}/{repo}",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Connecting Highlight AI

    Open Highlight AI and click the plugins icon (@ symbol) in the sidebar
    Click Installed Plugins at the top of the sidebar
    Select Custom Plugin
    Click Add a plugin using a custom SSE URL

Plugin name: gitmcp SSE URL: https://gitmcp.io/{owner}/{repo}

For more details on adding custom MCP servers to HighlightAI, refer to the documentation.
Connecting Augment Code

    Open Augment Code settings
    Navigate to the MCP section
    Add a new MCP server with the following details:

Name the MCP server: git-mcp Docs

Use this command:

npx mcp-remote https://gitmcp.io/{owner}/{repo}

Or use the following configuration:

{
  "mcpServers": {
    "git-mcp Docs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://gitmcp.io/{owner}/{repo}"
      ]
    }
  }
}

Connecting Msty AI

    Open Msty Studio
    Go to Tools > Import Tools from JSON Clipboard
    Paste the following configuration:

{
  "mcpServers": {
    "git-mcp Docs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://gitmcp.io/{owner}/{repo}"
      ]
    }
  }
}

For more details on configuring MCP servers in Augment Code, visit the Augment Code documentation.

    Note: Remember to replace {owner} and {repo} with the actual GitHub username/organization and repository name. You can also use the dynamic endpoint https://gitmcp.io/docs to allow your AI to access any repository on demand.

⚙ How It Works

GitMCP connects your AI assistant to GitHub repositories using the Model Context Protocol (MCP), a standard that lets AI tools request additional information from external sources.

What happens when you use GitMCP:

    You provide the GitMCP URL to your AI assistant (e.g., gitmcp.io/microsoft/typescript). GitMCP exposes tools like documentation fetching, smart search, code search, etc.
    Prompt the AI assistant on documentation/code-related questions.
    Your AI sends requests to GitMCP to use its tools (with your approval).
    GitMCP executes the AI's request and returns the requested data.
    Your AI receives the information and generates a more accurate, grounded response without hallucinations.

Supported Documentation

GitMCP currently supports the following documents (in order of priority):

    llms.txt
    AI-optimized version of the project's documentation
    README.md/root

💡 Examples

Here are some examples of how to use GitMCP with different AI assistants and repositories:
Example 1: Using Windsurf with a specific repository

For the GitHub repository https://github.com/microsoft/playwright-mcp, add https://gitmcp.io/microsoft/playwright-mcp as an MCP server to Windsurf.

Prompt to Claude:

    "How do I use the Playwright MCP"

Windsurf will pull the relevant documentation from GitMCP to implement the memory feature correctly.
Example 2: Using Cursor with a GitHub Pages site

For the GitHub Pages site langchain-ai.github.io/langgraph, add https://langchain-ai.gitmcp.io/langgraph as an MCP server to Cursor.

Prompt to Cursor:

    "Add memory to my LangGraph agent"

Cursor will pull the relevant documentation and code from GitMCP to correctly implement the memory feature.
Example 3: Using Claude Desktop with the dynamic endpoint

You don't have to pick specific repositories. The generic gitmcp.io/docs endpoint allows AI to pick the GitHub project on the fly!

Prompt to any AI assistant:

    "I want to learn about the OpenAI Whisper speech recognition model. Explain how it works.

Claude will pull the data from GitMCP and answer the question.
🛠️ Tools

GitMCP provides AI assistants with several valuable tools to help them access, understand, and query GitHub repositories.
fetch_<repo-name>_documentation

This tool gets the primary documentation from a GitHub repository. It works by retrieving relevant documentation (e.g., llms.txt). This gives the AI a good overview of what the project is about

When it's useful: For general questions about a project's purpose, features, or how to get started
search_<repo-name>_documentation

This tool lets the AI search through a repository's documentation by providing a specific search query. Instead of loading all the documentation (which could be very large), it uses intelligent search to find just the relevant parts.

When it's useful: For specific questions about particular features, functions, or concepts within a project
fetch_url_content

This tool helps the AI get information from links mentioned in the documentation. It retrieves the content from those links and converts it to a format the AI can easily read.

When it's useful: When documentation references external information that would help answer your question
search_<repo-name>_code

This tool searches through the actual code in the repository using GitHub's code search. It helps AI find specific code examples or implementation details.

When it's useful: When you want examples of how something is implemented or need technical details not covered in documentation

    Note: When using the dynamic endpoint (gitmcp.io/docs), these tools are named slightly differently (fetch_generic_documentation, search_generic_code, and search_generic_documentation) and need additional information about which repository to access.

📊 Badge

GitMCP has a badge to your repository's README. It allows users to quickly access your documentation through their IDE or browser (using the embedded chat). It also showcases how many times your documentation has been accessed through GitMCP.

Example (idosal/git-mcp): GitMCP
Adding the Badge to Your Repository

Add the following to your README.md:

[![GitMCP](https://img.shields.io/endpoint?url=https://gitmcp.io/badge/OWNER/REPO)](https://gitmcp.io/OWNER/REPO)

Replace OWNER with your GitHub username or organization, and REPO with your repository name.
How We Count Views

Increment for each tool call on the specific repository.
Customizing the Badge

You can customize the badge's appearance with parameters:
Parameter 	Description 	Default 	Example
color 	Color for the badge value 	aquamarine 	?color=green
label 	Badge label 	GitMCP 	Documentation

Please reach out!
❓ FAQ
What is the Model Context Protocol?

The Model Context Protocol is a standard that allows AI assistants to request and receive additional context from external sources in a structured manner, enhancing their understanding and performance.
Does GitMCP work with any AI assistant?

Yes, GitMCP is compatible with any AI assistant supporting the Model Context Protocol, including tools like Cursor, VSCode, Claude, etc.
Is GitMCP compatible with all GitHub projects?

Absolutely! GitMCP works with any public GitHub repository without requiring any modifications. It prioritizes the llms.txt file and falls back to README.md or other pages if the former is unavailable. Future updates aim to support additional documentation methods and even generate content dynamically.
Does GitMCP cost money?

No, GitMCP is a free service to the community with no associated costs.
🔒 Privacy

GitMCP is deeply committed to its users' privacy. The service doesn't have access to or store any personally identifiable information as it doesn't require authentication. In addition, it doesn't store any queries sent by the agents. Moreover, as GitMCP is an open-source project, it can be deployed independently in your environment.

GitMCP only accesses content that is already publicly available and only when queried by a user. GitMCP does not automatically scrape repositories. Before accessing any GitHub Pages site, the code checks for robots.txt rules and follows the directives set by site owners, allowing them to opt out. Please note that GitMCP doesn't permanently store data regarding the GitHub projects or their content.
👥 Contributing

We welcome contributions, feedback, and ideas! Please review our contribution guidelines.
Local Development Setup

Clone the repository

git clone https://github.com/idosal/git-mcp.git
cd git-mcp

Install dependencies

pnpm install

Run locally for development

npm run dev
# or
pnpm dev

Using MCP Inspector for Testing

Install the MCP Inspector tool:

npx @modelcontextprotocol/inspector

    In the inspector interface:
        Set Transport Type to SSE
        Enter your GitMCP URL (e.g., http://localhost:5173/docs)
        Click "Connect"

📄 License

This project is licensed under the Apache License 2.0.
Disclaimer

GitMCP is provided "as is" without warranty of any kind. While we strive to ensure the reliability and security of our service, we are not responsible for any damages or issues that may arise from its use. GitHub projects accessed through GitMCP are subject to their respective owners' terms and conditions. GitMCP is not affiliated with GitHub or any of the mentioned AI tools.
Star History

Star History Chart
About

Put an end to code hallucinations! GitMCP is a free, open-source, remote MCP server for any GitHub project
gitmcp.io
Topics
git ai mcp cursor copilot agents claude llm agentic-ai
Resources
Readme
License
Apache-2.0 license
Contributing
Contributing
Security policy
Security policy
Activity
Stars
7.4k stars
Watchers
40 watching
Forks
644 forks
Report repository
Contributors 15

    @idosal
    @liady
    @Copilot
    @AshAnand34
    @tosh
    @Livshitz
    @gkorland
    @macoughl
    @oilbeater
    @sylg
    @eladcandroid
    @chaoliu719
    @Naseem77
    @umuthopeyildirim
    @dependabot[bot]

Deployments

Languages

TypeScript 98.3%
CSS 1.6%

    JavaScript 0.1% 

Footer
© 2026 GitHub, Inc.
Footer navigation

    Terms
    Privacy
    Security
    Status
    Community
    Docs
    Contact

Copied!



https://github.com/mcp/huggingface/hf-mcp-server

    MCP Registry
    Hugging Face

Hugging Face Official MCP Server

Welcome to the official Hugging Face MCP Server 🤗. Connect your LLM to the Hugging Face Hub and thousands of Gradio AI Applications.
Installing the MCP Server

Follow the instructions below to get started:
Install in Claude Desktop or claude.ai

Install in Claude Code

Install in Claude Code

Install in Claude Code

Install in Gemini CLI



Install in Gemini CLI



Install in Gemini CLI



Install in VSCode

Install in VSCode

Install in Cursor

Install in Cursor

Once installed, navigate to https://huggingface.co/settings/mcp to configure your Tools and Spaces.

Tip

Add ?no_image_content=true to the URL to remove ImageContent blocks from Gradio Servers.

hf_mcp_server_small
Quick Guide (Repository Packages)

This repo contains:

    (/mcp) MCP Implementations of Hub API and Search endpoints for integration with MCP Servers.
    (/app) An MCP Server and Web Application for deploying endpoints.

MCP Server

The following transports are supported:

    STDIO
    SSE (To be deprecated, but still commonly deployed).
    StreamableHTTP
    StreamableHTTP in Stateless JSON Mode (StreamableHTTPJson)

The Web Application and HTTP Transports start by default on Port 3000.

SSE and StreamableHTTP services are available at /sse and /mcp respectively. Although though not strictly enforced by the specification this is common convention.

Tip

The Web Application allows you to switch tools on and off. For STDIO, SSE and StreamableHTTP this will send a ToolListChangedNotification to the MCP Client. In StreamableHTTPJSON mode the tool will not be listed when the client next requests the tool lists.
Running Locally

You can run the MCP Server locally with either npx or docker.

npx @llmindset/hf-mcp-server       # Start in STDIO mode
npx @llmindset/hf-mcp-server-http  # Start in Streamable HTTP mode
npx @llmindset/hf-mcp-server-json  # Start in Streamable HTTP (JSON RPC) mode

To run with docker:

docker pull ghcr.io/evalstate/hf-mcp-server:latest
docker run --rm -p 3000:3000 ghcr.io/evalstate/hf-mcp-server:latest

image

All commands above start the Management Web interface on http://localhost:3000/. The Streamable HTTP server is accessible on http://localhost:3000/mcp. See [Environment Variables](#Environment Variables) for configuration options. Docker defaults to Streamable HTTP (JSON RPC) mode.
Developing OpenAI Apps SDK Components

To build and test the Apps SDK component, run

cd packages/app
npm run dev:widget

Then open http://localhost:5173/gradio-widget-dev.html. This will bring up a browser with HMR where you can send Structured Content to the components for testing.

skybridge-viewer
Development

This project uses pnpm for build and development. Corepack is used to ensure everyone uses the same pnpm version (10.12.3).

# Install dependencies
pnpm install

# Build all packages
pnpm build

Build Commands

pnpm run clean -> clean build artifacts

pnpm run build -> build packages

pnpm run start -> start the mcp server application

pnpm run buildrun -> clean, build and start

pnpm run dev -> concurrently watch mcp and start dev server with HMR
Docker Build

Build the image:

docker build -t hf-mcp-server .

Run with default settings (Streaming HTTP JSON Mode), Dashboard on Port 3000:

docker run --rm -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

Run STDIO MCP Server:

docker run -i --rm -e TRANSPORT=stdio -p 3000:3000 -e DEFAULT_HF_TOKEN=hf_xxx hf-mcp-server

TRANSPORT can be stdio, sse, streamingHttp or streamingHttpJson (default).
Transport Endpoints

The different transport types use the following endpoints:

    SSE: /sse (with message endpoint at /message)
    Streamable HTTP: /mcp (regular or JSON mode)
    STDIO: Uses stdin/stdout directly, no HTTP endpoint

Stateful Connection Management

The sse and streamingHttp transports are both stateful - they maintain a connection with the MCP Client through an SSE connection. When using these transports, the following configuration options take effect:
Environment Variable 	Default 	Description
MCP_CLIENT_HEARTBEAT_INTERVAL 	30000ms 	How often to check SSE connection health
MCP_CLIENT_CONNECTION_CHECK 	90000ms 	How often to check for stale sessions
MCP_CLIENT_CONNECTION_TIMEOUT 	300000ms 	Remove sessions inactive for this duration
MCP_PING_ENABLED 	true 	Enable ping keep-alive for sessions
MCP_PING_INTERVAL 	30000ms 	Interval between ping cycles
Environment Variables

The server respects the following environment variables:

    TRANSPORT: The transport type to use (stdio, sse, streamableHttp, or streamableHttpJson)
    DEFAULT_HF_TOKEN: ⚠️ Requests are serviced with the HF_TOKEN received in the Authorization: Bearer header. The DEFAULT_HF_TOKEN is used if no header was sent. Only set this in Development / Test environments or for local STDIO Deployments. ⚠️
    If running with stdio transport, HF_TOKEN is used if DEFAULT_HF_TOKEN is not set.
    HF_API_TIMEOUT: Timeout for Hugging Face API requests in milliseconds (default: 12500ms / 12.5 seconds)
    USER_CONFIG_API: URL to use for User settings (defaults to Local front-end)
    MCP_STRICT_COMPLIANCE: set to True for GET 405 rejects in JSON Mode (default serves a welcome page).
    AUTHENTICATE_TOOL: whether to include an Authenticate tool to issue an OAuth challenge when called
    SEARCH_ENABLES_FETCH: When set to true, automatically enables the hf_doc_fetch tool whenever hf_doc_search is enabled

About
Hugging Face logo

Hugging Face


Analysis API

Authentication

To get started with the Analysis REST API, you’ll need an API key.
Generate Your API Key

In the Analysis web app, go to the Settings page to create a new API key. You can have at most 3 API keys at a time.

Analysis REST API Key creation interface
Use Your API Key

To authenticate your requests, pass the API key in the X-Goog-Api-Key header of your API calls.

Keep your API keys secure. Don’t share them or embed them in public code. For your protection, any API keys found to be publicly exposed will be automatically disabled to prevent abuse.
API concepts

The Analysis REST API is built around a few core resources. Understanding these will help you use the API effectively.

    Source — An input source for the agent (e.g., a GitHub repository). Before using a source using the API, you must first install the Analysis GitHub app through the Analysis web app.
    Session — A continuous unit of work within a specific context, similar to a chat session. A session is initiated with a prompt and a source.
    Activity — A single unit of work within a Session. A Session contains multiple activities from both the user and the agent, such as generating a plan, sending a message, or updating progress.

Your first API call

We’ll walk through creating your first session with the Analysis REST API using curl.

    List your available sources

First, you need to find the name of the source you want to work with (e.g., your GitHub repo). This command will return a list of all sources you have connected to Analysis.

curl -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/sources

The response will look something like this:

{
  "sources": [
    {
      "name": "sources/github/bobalover/boba",
      "id": "github/bobalover/boba",
      "githubRepo": {
        "owner": "bobalover",
        "repo": "boba"
      }
    }
  ],
  "nextPageToken": "github/bobalover/boba-web"
}

Create a new session

Now, create a new session. You’ll need the source name from the previous step. This request tells Analysis to create a boba app in the specified repository.

curl 'https://jules.googleapis.com/v1alpha/sessions' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -d '{
    "prompt": "Create a boba app!",
    "sourceContext": {
      "source": "sources/github/bobalover/boba",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "automationMode": "AUTO_CREATE_PR",
    "title": "Boba App"
  }'

The automationMode field is optional. By default, no PR will be automatically created.

The immediate response will look something like this:

{
  "name": "sessions/31415926535897932384",
  "id": "31415926535897932384",
  "title": "Boba App",
  "sourceContext": {
    "source": "sources/github/bobalover/boba",
    "githubRepoContext": {
      "startingBranch": "main"
    }
  },
  "prompt": "Create a boba app!"
}

You can poll the latest session information using GetSession or ListSessions. For example, if a PR was automatically created, you can see the PR in the session output:

{
  "name": "sessions/31415926535897932384",
  "id": "31415926535897932384",
  "title": "Boba App",
  "sourceContext": {
    "source": "sources/github/bobalover/boba",
    "githubRepoContext": {
      "startingBranch": "main"
    }
  },
  "prompt": "Create a boba app!",
  "outputs": [
    {
      "pullRequest": {
        "url": "https://github.com/bobalover/boba/pull/35",
        "title": "Create a boba app",
        "description": "This change adds the initial implementation of a boba app."
      }
    }
  ]
}

By default, sessions created through the API will have their plans automatically approved. If you want to create a session that requires explicit plan approval, set the requirePlanApproval field to true.
List sessions

You can list your sessions as follows:

curl 'https://jules.googleapis.com/v1alpha/sessions?pageSize=5' \
  -H "x-goog-api-key: $JULES_API_KEY"

Approve a plan

If your session requires explicit plan approval, you can approve the latest plan as follows:

curl 'https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY"

Interact with the agent

To list activities in a session:

curl 'https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?pageSize=30' \
  -H "x-goog-api-key: $JULES_API_KEY"

To send a message to the agent:

curl 'https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage' \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -d '{
    "prompt": "Can you make the app corgi themed?"
  }'

The response will be empty because the agent will send its response in the next activity. To see the agent’s response, list the activities again.


Sessions

Sessions are the core resource in the Analysis REST API. A session represents a unit of work where Analysis executes a coding task on your repository.
Create a Session
POST
/v1alpha/sessions

Creates a new session to start a coding task.
Request Body
prompt
required string

The task description for Analysis to execute.
title
string

Optional title for the session. If not provided, the system will generate one.
sourceContext
required SourceContext

The source repository and branch context for this session.
requirePlanApproval
boolean

If true, plans require explicit approval before execution. If not set, plans are auto-approved.
automationMode
string

Automation mode. Use 'AUTO_CREATE_PR' to automatically create pull requests when code changes are ready.
Example Request

curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add comprehensive unit tests for the authentication module",
    "title": "Add auth tests",
    "sourceContext": {
      "source": "sources/github-myorg-myrepo",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "requirePlanApproval": true
  }' \
  https://jules.googleapis.com/v1alpha/sessions

Response

Returns the created Session object:

{
  "name": "1234567",
  "id": "abc123",
  "prompt": "Add comprehensive unit tests for the authentication module",
  "title": "Add auth tests",
  "state": "QUEUED",
  "url": "https://jules.google.com/session/abc123",
  "createTime": "2024-01-15T10:30:00Z",
  "updateTime": "2024-01-15T10:30:00Z"
}

List Sessions
GET
/v1alpha/sessions

Lists all sessions for the authenticated user.
Query Parameters
pageSize
integer query

Number of sessions to return (1-100). Defaults to 30.
pageToken
string query

Page token from a previous ListSessions response.
Example Request

curl -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10"

Response

{
  "sessions": [
    {
      "name": "1234567",
      "id": "abc123",
      "title": "Add auth tests",
      "state": "COMPLETED",
      "createTime": "2024-01-15T10:30:00Z",
      "updateTime": "2024-01-15T11:45:00Z"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
}

Get a Session
GET
/v1alpha/sessions/{sessionId}

Retrieves a single session by ID.
Path Parameters
name
required string path

The resource name of the session. Format: sessions/{session}

Pattern: ^sessions/[^/]+$
Example Request

curl -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/1234567

Response

Returns the full Session object including outputs if the session has completed:

{
  "name": "1234567",
  "id": "abc123",
  "prompt": "Add comprehensive unit tests for the authentication module",
  "title": "Add auth tests",
  "state": "COMPLETED",
  "url": "https://jules.google.com/session/abc123",
  "createTime": "2024-01-15T10:30:00Z",
  "updateTime": "2024-01-15T11:45:00Z",
  "outputs": [
    {
      "pullRequest": {
        "url": "https://github.com/myorg/myrepo/pull/42",
        "title": "Add auth tests",
        "description": "Added unit tests for authentication module"
      }
    }
  ]
}

Delete a Session
DELETE
/v1alpha/sessions/{sessionId}

Deletes a session.
Path Parameters
name
required string path

The resource name of the session to delete. Format: sessions/{session}

Pattern: ^sessions/[^/]+$
Example Request

curl -X DELETE \
  -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/1234567

Response

Returns an empty response on success.
Send a Message
POST
/v1alpha/sessions/{sessionId}:sendMessage

Sends a message from the user to an active session.

Use this endpoint to provide feedback, answer questions, or give additional instructions to Analysis during an active session.
Path Parameters
session
required string path

The resource name of the session. Format: sessions/{session}

Pattern: ^sessions/[^/]+$
Request Body
prompt
required string

The message to send to the session.
Example Request

curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please also add integration tests for the login flow"
  }' \
  https://jules.googleapis.com/v1alpha/1234567:sendMessage

Response

Returns an empty SendMessageResponse on success.
Approve a Plan
POST
/v1alpha/sessions/{sessionId}:approvePlan

Approves a pending plan in a session.

This endpoint is only needed when requirePlanApproval was set to true when creating the session.
Path Parameters
session
required string path

The resource name of the session. Format: sessions/{session}

Pattern: ^sessions/[^/]+$
Example Request

curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://jules.googleapis.com/v1alpha/1234567:approvePlan

Response

Returns an empty ApprovePlanResponse on success.
Session States

Sessions progress through the following states:
State	Description
QUEUED	Session is waiting to be processed
PLANNING	Analysis is analyzing the task and creating a plan
AWAITING_PLAN_APPROVAL	Plan is ready and waiting for user approval
AWAITING_USER_FEEDBACK	Analysis needs additional input from the user
IN_PROGRESS	Analysis is actively working on the task
PAUSED	Session is paused
COMPLETED	Task completed successfully
FAILED	Task failed to complete
Previous
Authentication


Activities

Activities represent events that occur during a session. Use the Activities API to monitor progress, retrieve messages, and access artifacts like code changes.
List Activities
GET
/v1alpha/sessions/{sessionId}/activities

Lists all activities for a session.
Path Parameters
parent
required string path

The parent session. Format: sessions/{session}

Pattern: ^sessions/[^/]+$
Query Parameters
pageSize
integer query

Number of activities to return (1-100). Defaults to 50.
pageToken
string query

Page token from a previous ListActivities response.
Example Request

curl -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/1234567/activities?pageSize=20"

Response

{
  "activities": [
    {
      "name": "1234567/activities/act1",
      "id": "act1",
      "originator": "system",
      "description": "Session started",
      "createTime": "2024-01-15T10:30:00Z"
    },
    {
      "name": "1234567/activities/act2",
      "id": "act2",
      "originator": "agent",
      "description": "Plan generated",
      "planGenerated": {
        "plan": {
          "id": "plan1",
          "steps": [
            {
              "id": "step1",
              "index": 0,
              "title": "Analyze existing code",
              "description": "Review the authentication module structure"
            },
            {
              "id": "step2",
              "index": 1,
              "title": "Write unit tests",
              "description": "Create comprehensive test coverage"
            }
          ],
          "createTime": "2024-01-15T10:31:00Z"
        }
      },
      "createTime": "2024-01-15T10:31:00Z"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjIwfQ=="
}

Get an Activity
GET
/v1alpha/sessions/{sessionId}/activities/{activityId}

Retrieves a single activity by ID.
Path Parameters
name
required string path

The resource name of the activity. Format: sessions/{session}/activities/{activity}

Pattern: ^sessions/[^/]+/activities/[^/]+$
Example Request

curl -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/1234567/activities/act2

Response

Returns the full Activity object:

{
  "name": "1234567/activities/act2",
  "id": "act2",
  "originator": "agent",
  "description": "Code changes ready",
  "createTime": "2024-01-15T11:00:00Z",
  "artifacts": [
    {
      "changeSet": {
        "source": "sources/github-myorg-myrepo",
        "gitPatch": {
          "baseCommitId": "a1b2c3d4",
          "unidiffPatch": "diff --git a/tests/auth.test.js...",
          "suggestedCommitMessage": "Add unit tests for authentication module"
        }
      }
    }
  ]
}

Activity Types

Activities have different types based on what occurred. Each activity will have exactly one of these event fields populated:
Plan Generated

Indicates Analysis has created a plan for the task:

{
  "planGenerated": {
    "plan": {
      "id": "plan1",
      "steps": [
        { "id": "step1", "index": 0, "title": "Step title", "description": "Details" }
      ],
      "createTime": "2024-01-15T10:31:00Z"
    }
  }
}

Plan Approved

Indicates a plan was approved (by user or auto-approved):

{
  "planApproved": {
    "planId": "plan1"
  }
}

User Messaged

A message from the user:

{
  "userMessaged": {
    "userMessage": "Please also add integration tests"
  }
}

Agent Messaged

A message from Analysis:

{
  "agentMessaged": {
    "agentMessage": "I've completed the unit tests. Would you like me to add integration tests as well?"
  }
}

Progress Updated

A status update during execution:

{
  "progressUpdated": {
    "title": "Writing tests",
    "description": "Creating test cases for login functionality"
  }
}

Session Completed

The session finished successfully:

{
  "sessionCompleted": {}
}

Session Failed

The session encountered an error:

{
  "sessionFailed": {
    "reason": "Unable to install dependencies"
  }
}

Artifacts

Activities may include artifacts—outputs produced during execution:
Code Changes (ChangeSet)

{
  "artifacts": [
    {
      "changeSet": {
        "source": "sources/github-myorg-myrepo",
        "gitPatch": {
          "baseCommitId": "a1b2c3d4e5f6",
          "unidiffPatch": "diff --git a/src/auth.js b/src/auth.js\n...",
          "suggestedCommitMessage": "Add authentication tests"
        }
      }
    }
  ]
}

Bash Output

{
  "artifacts": [
    {
      "bashOutput": {
        "command": "npm test",
        "output": "All tests passed (42 passing)",
        "exitCode": 0
      }
    }
  ]
}

Media

{
  "artifacts": [
    {
      "media": {
        "mimeType": "image/png",
        "data": "base64-encoded-data..."
      }
    }
  ]
}

Sources

Sources represent repositories connected to Analysis. Currently, Analysis supports GitHub repositories. Use the Sources API to list available repositories and get details about specific sources.

Sources are created when you connect a GitHub repository to Analysis through the web interface. The API currently only supports reading sources, not creating them.
List Sources
GET
/v1alpha/sources

Lists all sources (repositories) connected to your account.
Query Parameters
pageSize
integer query

Number of sources to return (1-100). Defaults to 30.
pageToken
string query

Page token from a previous ListSources response.
filter
string query

Filter expression based on AIP-160. Example: 'name=sources/source1 OR name=sources/source2'
Example Request

curl -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?pageSize=10"

Response

{
  "sources": [
    {
      "name": "sources/github-myorg-myrepo",
      "id": "github-myorg-myrepo",
      "githubRepo": {
        "owner": "myorg",
        "repo": "myrepo",
        "isPrivate": false,
        "defaultBranch": {
          "displayName": "main"
        },
        "branches": [
          { "displayName": "main" },
          { "displayName": "develop" },
          { "displayName": "feature/auth" }
        ]
      }
    },
    {
      "name": "sources/github-myorg-another-repo",
      "id": "github-myorg-another-repo",
      "githubRepo": {
        "owner": "myorg",
        "repo": "another-repo",
        "isPrivate": true,
        "defaultBranch": {
          "displayName": "main"
        },
        "branches": [
          { "displayName": "main" }
        ]
      }
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
}

Filtering

Use the filter parameter to retrieve specific sources:

# Get a specific source
curl -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?filter=name%3Dsources%2Fgithub-myorg-myrepo"

# Get multiple sources
curl -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?filter=name%3Dsources%2Fsource1%20OR%20name%3Dsources%2Fsource2"

Get a Source
GET
/v1alpha/sources/{sourceId}

Retrieves a single source by ID.
Path Parameters
name
required string path

The resource name of the source. Format: sources/{source}

Pattern: ^sources/.*$
Example Request

curl -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/sources/github-myorg-myrepo

Response

Returns the full Source object:

{
  "name": "sources/github-myorg-myrepo",
  "id": "github-myorg-myrepo",
  "githubRepo": {
    "owner": "myorg",
    "repo": "myrepo",
    "isPrivate": false,
    "defaultBranch": {
      "displayName": "main"
    },
    "branches": [
      { "displayName": "main" },
      { "displayName": "develop" },
      { "displayName": "feature/auth" },
      { "displayName": "feature/tests" }
    ]
  }
}

Using Sources with Sessions

When creating a session, reference a source using its resource name in the sourceContext:

curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add unit tests for the auth module",
    "sourceContext": {
      "source": "sources/github-myorg-myrepo",
      "githubRepoContext": {
        "startingBranch": "develop"
      }
    }
  }' \
  https://jules.googleapis.com/v1alpha/sessions

Use the List Sources endpoint to discover available source names, then use the Get Source endpoint to see available branches before creating a session.
Previous
Activities
Next
Types 


This page documents all data types used in the Analysis REST API.
Core Resources
Session

A session represents a unit of work where Analysis executes a coding task.
Session

A session is a contiguous amount of work within the same context.
name
string

Output only. The full resource name (e.g., 'sessions/{session}').
id
string

Output only. The session ID.
prompt
required string

The task description for Analysis to execute.
title
string

Optional title. If not provided, the system generates one.
state
SessionState

Output only. Current state of the session.
url
string

Output only. URL to view the session in the Analysis web app.
sourceContext
required SourceContext

The source repository and branch context.
requirePlanApproval
boolean

Input only. If true, plans require explicit approval.
automationMode
AutomationMode

Input only. Automation mode for the session.
outputs
SessionOutput []

Output only. Results of the session (e.g., pull requests).
createTime
string (google-datetime)

Output only. When the session was created.
updateTime
string (google-datetime)

Output only. When the session was last updated.
SessionState

Enum representing the current state of a session:
Value	Description
STATE_UNSPECIFIED	State is unspecified
QUEUED	Session is waiting to be processed
PLANNING	Analysis is creating a plan
AWAITING_PLAN_APPROVAL	Plan is ready for user approval
AWAITING_USER_FEEDBACK	Analysis needs user input
IN_PROGRESS	Analysis is actively working
PAUSED	Session is paused
FAILED	Session failed
COMPLETED	Session completed successfully
AutomationMode

Enum for session automation settings:
Value	Description
AUTOMATION_MODE_UNSPECIFIED	No automation (default)
AUTO_CREATE_PR	Automatically create a pull request when code changes are ready
Activity

An activity represents a single event within a session.
Activity

An activity is a single unit of work within a session.
name
string

The full resource name (e.g., 'sessions/{session}/activities/{activity}').
id
string

Output only. The activity ID.
originator
string

The entity that created this activity ('user', 'agent', or 'system').
description
string

Output only. A description of this activity.
createTime
string (google-datetime)

Output only. When the activity was created.
artifacts
Artifact []

Output only. Artifacts produced by this activity.
planGenerated
PlanGenerated

A plan was generated.
planApproved
PlanApproved

A plan was approved.
userMessaged
UserMessaged

The user posted a message.
agentMessaged
AgentMessaged

Analysis posted a message.
progressUpdated
ProgressUpdated

A progress update occurred.
sessionCompleted
SessionCompleted

The session completed.
sessionFailed
SessionFailed

The session failed.
Source

A source represents a connected repository.
Source

An input source of data for a session.
name
string

The full resource name (e.g., 'sources/{source}').
id
string

Output only. The source ID.
githubRepo
GitHubRepo

GitHub repository details.
Plans
Plan
Plan

A sequence of steps that Analysis will take to complete the task.
id
string

Output only. Unique ID for this plan within a session.
steps
PlanStep []

Output only. The steps in the plan.
createTime
string (google-datetime)

Output only. When the plan was created.
PlanStep
PlanStep

A single step in a plan.
id
string

Output only. Unique ID for this step within a plan.
index
integer (int32)

Output only. 0-based index in the plan.
title
string

Output only. The title of the step.
description
string

Output only. Detailed description of the step.
Artifacts
Artifact
Artifact

A single unit of data produced by an activity.
changeSet
ChangeSet

Code changes produced.
bashOutput
BashOutput

Command output produced.
media
Media

Media file produced (e.g., image, video).
ChangeSet
ChangeSet

A set of changes to be applied to a source.
source
string

The source this change set applies to. Format: sources/{source}
gitPatch
GitPatch

The patch in Git format.
GitPatch
GitPatch

A patch in Git format.
baseCommitId
string

The commit ID the patch should be applied to.
unidiffPatch
string

The patch in unified diff format.
suggestedCommitMessage
string

A suggested commit message for the patch.
BashOutput
BashOutput

Output from a bash command.
command
string

The bash command that was executed.
output
string

Combined stdout and stderr output.
exitCode
integer (int32)

The exit code of the command.
Media
Media

A media file output.
mimeType
string

The MIME type of the media (e.g., 'image/png').
data
string (byte)

Base64-encoded media data.
GitHub Types
GitHubRepo
GitHubRepo

A GitHub repository.
owner
string

The repository owner (user or organization).
repo
string

The repository name.
isPrivate
boolean

Whether the repository is private.
defaultBranch
GitHubBranch

The default branch.
branches
GitHubBranch []

List of active branches.
GitHubBranch
GitHubBranch

A GitHub branch.
displayName
string

The branch name.
GitHubRepoContext
GitHubRepoContext

Context for using a GitHub repo in a session.
startingBranch
required string

The branch to start the session from.
Context Types
SourceContext
SourceContext

Context for how to use a source in a session.
source
required string

The source resource name. Format: sources/{source}
githubRepoContext
GitHubRepoContext

Context for GitHub repositories.
Output Types
SessionOutput
SessionOutput

An output of a session.
pullRequest
PullRequest

A pull request created by the session.
PullRequest
PullRequest

A pull request.
url
string

The URL of the pull request.
title
string

The title of the pull request.
description
string

The description of the pull request.
Activity Event Types
PlanGenerated
PlanGenerated

A plan was generated.
plan
Plan

The generated plan.
PlanApproved
PlanApproved

A plan was approved.
planId
string

The ID of the approved plan.
UserMessaged
UserMessaged

The user posted a message.
userMessage
string

The message content.
AgentMessaged
AgentMessaged

Analysis posted a message.
agentMessage
string

The message content.
ProgressUpdated
ProgressUpdated

A progress update occurred.
title
string

The title of the update.
description
string

Details about the progress.
SessionCompleted
SessionCompleted

The session completed successfully.

No additional properties.
SessionFailed
SessionFailed

The session failed.
reason
string

The reason for the failure.
Request/Response Types
SendMessageRequest
SendMessageRequest

Request to send a message to a session.
prompt
required string

The message to send.
SendMessageResponse
SendMessageResponse

Response from sending a message.

Empty response on success.
ApprovePlanRequest
ApprovePlanRequest

Request to approve a plan.

Empty request body.
ApprovePlanResponse
ApprovePlanResponse

Response from approving a plan.

Empty response on success.
ListSessionsResponse
ListSessionsResponse

Response from listing sessions.
sessions
Session []

The list of sessions.
nextPageToken
string

Token for the next page of results.
ListActivitiesResponse
ListActivitiesResponse

Response from listing activities.
activities
Activity []

The list of activities.
nextPageToken
string

Token for the next page of results.
ListSourcesResponse
ListSourcesResponse

Response from listing sources.
sources
Source []

The list of sources.
nextPageToken
string

Token for the next page of results.