# GitHub (read-only)

> GitHub (read-only) is an open-source MCP server for developer tools. Read-only GitHub repos, issues, PRs and commits with benchmark-tuned tool descriptions. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API
- **Website:** https://abdulmuhaiminkhan.github.io/github-mcp/
- **Repository:** https://github.com/abdulmuhaiminkhan/github-mcp
- **MCP Registry name:** io.github.AbdulMuhaiminKhan/github-mcp
- **Categories:** developer tools
- **Listing updated:** 2026-11-16

## About

This Python server is as much a benchmarking project as a GitHub connector. The author measured how often a small local model picks the right tool with the right arguments, then rewrote tool descriptions and input handling. Accuracy went from 63% to 95% on the tuned questions and 60% to 90% on held-out ones. Most of the gain, 17 of 32 points, came from accepting bare repository names rather than owner/name, with 8 from stating the limit range and 7 from rewording.

Six tools cover listing repositories and reading repositories, open issues, issue search, pull requests and recent commits. Access is least-privilege: a fine-grained, read-only token with Metadata, Contents, Issues and Pull requests permissions stays in the server process and never reaches the model. The server retries with backoff, handles rate limits and caches with ETags.

A GITHUB_MCP_TOOLSET variable chooses v2 (default) or the v1 and v1b baselines. The repository also includes the evaluation harness and a results dashboard. Known gaps include merged PRs, sorting by stars and closed issues.

## Features

- **Six read-only tools:** Repositories, issues, pull requests and commits.
- **Bare repo names:** Accepts a repository name without the owner prefix.
- **Least-privilege token:** Fine-grained read-only token kept out of the model.
- **Rate-limit handling:** Retries with backoff, ETag caching and exact totals.
- **Switchable descriptions:** Choose v2 or baseline v1 and v1b tool descriptions.
- **Reusable benchmark:** Harness can benchmark other MCP servers.

## Good for

- Ask an assistant about open issues across your repos
- Review recent commits for a repository
- Search issues without giving write access
- Study how tool descriptions affect model accuracy

## Install

### Claude Code (Terminal)

```sh
claude mcp add github-mcp --env GITHUB_TOKEN='<GITHUB_TOKEN>' -- uvx github-mcp-readonly
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "uvx",
      "args": [
        "github-mcp-readonly"
      ],
      "env": {
        "GITHUB_TOKEN": "<GITHUB_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "uvx",
      "args": [
        "github-mcp-readonly"
      ],
      "env": {
        "GITHUB_TOKEN": "<GITHUB_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "github-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "github-mcp-readonly"
      ],
      "env": {
        "GITHUB_TOKEN": "<GITHUB_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "uvx",
      "args": [
        "github-mcp-readonly"
      ],
      "env": {
        "GITHUB_TOKEN": "<GITHUB_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "uvx",
      "args": [
        "github-mcp-readonly"
      ],
      "env": {
        "GITHUB_TOKEN": "<GITHUB_TOKEN>"
      }
    }
  }
}
```

## Tools

- `list_repositories`: Lists repositories.
- `get_repository`: Gets one repository.
- `list_open_issues`: Lists open issues.
- `search_issues`: Searches issues.
- `list_pull_requests`: Lists pull requests.
- `get_recent_commits`: Gets recent commits.

## FAQ

### What token does it need?

A fine-grained GitHub token with read-only Metadata, Contents, Issues and Pull requests access.

### Can it change anything on GitHub?

No, it is read-only.

### What does it not support yet?

The README lists merged PRs, sorting by stars and closed issues as unmet requests.

### How do I install it?

From PyPI as github-mcp-readonly, running over stdio.

### Is GitHub (read-only) free?

Yes. GitHub (read-only) is open source, so you can use and self-host it for free.

### How do I add GitHub (read-only) to Claude Code?

Run this command in your terminal: claude mcp add github-mcp --env GITHUB_TOKEN='<GITHUB_TOKEN>' -- uvx github-mcp-readonly

### What are the best alternatives to GitHub (read-only)?

The closest alternatives to GitHub (read-only) are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/github-read-only
