Metadata-Version: 2.4
Name: workos-github-mcp-server
Version: 1.0.1
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

**Recommended — no pre-install required (uses [uv](https://docs.astral.sh/uv/)):**
```bash
# uv manages a temporary isolated environment automatically
uvx --from workos-github-mcp-server github-mcp-server
```

**Or install permanently with pip:**
```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"

# Recommended: run via uvx (no install needed)
uvx --from workos-github-mcp-server github-mcp-server

# Or if installed via pip
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

> **Note:** Use `uvx --from workos-github-mcp-server github-mcp-server` in all configs below. The `--from` flag is needed because the PyPI package name (`workos-github-mcp-server`) differs from the CLI entry point (`github-mcp-server`). You must have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (`brew install uv` on macOS).

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["--from", "workos-github-mcp-server", "github-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your-token"
      }
    }
  }
}
```

> **Alternative** — if you have installed via `pip install workos-github-mcp-server` and prefer not to use uvx, use the full absolute path to the binary instead:
> ```json
> { "command": "/path/to/your/bin/github-mcp-server" }
> ```
> Find the path with: `which github-mcp-server`

### Cursor

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):

```json
{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["--from", "workos-github-mcp-server", "github-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your-token"
      }
    }
  }
}
```

### VS Code (GitHub Copilot / MCP extension)

Edit `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-github-mcp-server", "github-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${input:githubToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "githubToken",
      "type": "promptString",
      "description": "GitHub Personal Access Token (ghp_... or github_pat_...)",
      "password": true
    }
  ]
}
```

### WorkOS / Custom Agents

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-github-mcp-server", "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
rm -rf dist/ build/ src/*.egg-info
python -m build
pip install "packaging>=24.2"   # required for Metadata 2.4 support in twine
twine check dist/*              # validate before uploading
twine upload dist/*
```

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

## License

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