# GitHub Issues MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI assistants like Claude list, search, and inspect issues on any **public GitHub repository** — in natural language.

Built with Python and the official `mcp` SDK, using GitHub's public REST API (no auth required for public repos).

## Why this exists

MCP is the emerging standard for connecting AI assistants to real data and tools. This server is a small, focused example of that pattern applied to GitHub issue tracking — useful on its own, and a clean reference if you're learning to build MCP servers.

## Tools exposed

| Tool | Description |
|---|---|
| `list_open_issues(owner, repo, limit)` | Lists the most recently updated open issues in a repo |
| `search_issues(owner, repo, query, limit)` | Searches issues (open or closed) by keyword |
| `get_issue_details(owner, repo, issue_number)` | Gets full details for a single issue |

## Setup

```bash
git clone https://github.com/<your-username>/github-issues-mcp.git
cd github-issues-mcp
pip install -r requirements.txt
```

Optional — to raise GitHub's rate limit from 60 to 5,000 requests/hour, set a personal access token:

```bash
export GITHUB_TOKEN=ghp_yourtokenhere
```

## Running standalone (manual test)

```bash
python test_server.py
```

This calls the tool functions directly against the live GitHub API so you can see them work without wiring up a full MCP client.

## Using it with Claude Desktop

Add this to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "github-issues": {
      "command": "python",
      "args": ["/absolute/path/to/github-issues-mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop, and you'll be able to ask things like:

> "List the open issues in facebook/react"
> "Search torvalds/linux issues for 'memory leak'"
> "Show me details on issue #500 in python/cpython"

## Project structure

```
github-issues-mcp/
├── server.py          # MCP server + tool definitions
├── test_server.py      # Manual test script (no MCP client needed)
├── requirements.txt
└── README.md
```

## License

MIT