GitHub MCP Server

A production-ready Model Context Protocol (MCP) 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):

# uv manages a temporary isolated environment automatically
uvx --from workos-github-mcp-server github-mcp-server

Or install permanently with pip:

pip install workos-github-mcp-server

Or install from source:

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

Quick Start

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
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 installed (brew install uv on macOS).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.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:

{ "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):

{
  "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:

{
  "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:

{
  "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

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

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

mcp-publisher login github
mcp-publisher publish

License

MIT — see LICENSE for details.