Metadata-Version: 2.4
Name: workos-github-mcp-server
Version: 1.0.0
Summary: MCP server for GitHub operations — manage repos, issues, pull requests, commits, gists, and more.
Author: WorkOS Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/workos/workos-github-mcp-server
Project-URL: Repository, https://github.com/workos/workos-github-mcp-server
Project-URL: Issues, https://github.com/workos/workos-github-mcp-server/issues
Keywords: mcp,github,model-context-protocol,ai-tools,devtools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# GitHub MCP Server

<!-- mcp-name: io.github.workos/github-mcp-server -->

A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for GitHub operations. Connect any AI agent to GitHub — manage repos, issues, pull requests, commits, gists, search code, and look up user profiles.

**This is an independent, generalized MCP server.** It is not tied to any specific project and can be connected to any AI agent that supports MCP (Claude Desktop, Cursor, WorkOS, or custom agents).

## Features

- 📦 **Repositories**: List, search, and get repo details
- 🐛 **Issues**: Create, read, update, search issues
- 🔀 **Pull Requests**: List, create, and inspect PRs
- 📝 **Commits**: Browse commit history
- 🔍 **Search**: Search code and issues across GitHub
- 👤 **Users**: Look up user profiles
- 📋 **Gists**: List and create gists

## Installation

```bash
pip install workos-github-mcp-server
```

Or install from source:
```bash
git clone https://github.com/workos/workos-github-mcp-server
cd workos-github-mcp-server
pip install -e .
```

## Quick Start

```bash
export GITHUB_TOKEN="ghp_your-personal-access-token"

# Run the server
github-mcp-server

# Or run as a Python module
python -m github_mcp_server
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_TOKEN` | ✅ Yes | GitHub Personal Access Token (`ghp_...` or `github_pat_...`) |

### Getting a GitHub Token

1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
2. Click **"Generate new token (classic)"** or **"Fine-grained tokens"**
3. Select scopes:
   - `repo` — full repository access (issues, PRs, commits)
   - `gist` — create and list gists
   - `read:user` — read user profiles
4. Copy the generated token

## Connecting to AI Agents

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your-token"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your-token"
      }
    }
  }
}
```

### WorkOS / Custom Agents

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "python",
      "args": ["-m", "github_mcp_server"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

## Available Tools (15)

| Tool | Description |
|------|-------------|
| `github_list_repos` | List repositories for a user or the authenticated user |
| `github_get_repo` | Get detailed repository information |
| `github_search_repos` | Search repositories across GitHub |
| `github_list_issues` | List issues in a repository |
| `github_create_issue` | Create a new issue |
| `github_get_issue` | Get issue details |
| `github_update_issue` | Update an existing issue |
| `github_search_issues` | Search issues and PRs across GitHub |
| `github_list_pull_requests` | List pull requests in a repository |
| `github_get_pull_request` | Get pull request details |
| `github_create_pull_request` | Create a new pull request |
| `github_list_commits` | List recent commits |
| `github_list_gists` | List gists for the authenticated user |
| `github_create_gist` | Create a new gist |
| `github_get_user` | Get user profile information |

## Development

```bash
git clone https://github.com/workos/workos-github-mcp-server
cd workos-github-mcp-server
pip install -e .

# Run tests
pytest

# Run the server locally
GITHUB_TOKEN=ghp_test python -m github_mcp_server
```

## Publishing

### To PyPI
```bash
pip install build twine
python -m build
twine upload dist/*
```

### To MCP Registry
```bash
mcp-publisher login github
mcp-publisher publish
```

## License

MIT — see [LICENSE](LICENSE) for details.
