github-ops-mcp

A small MCP server that lets an LLM (Claude Desktop, Claude Code, or any MCP client) search GitHub, clone repos into a sandboxed workspace, and run common read-only git / gh operations. Personal project — see plan.md for the design.

1. Prerequisites

Make sure these are installed and working before you continue:

git --version           # any recent git
gh --version            # GitHub CLI — https://cli.github.com/
python3 --version       # Python 3.11 or newer

Log in to GitHub once (opens a browser):

gh auth login

Verify:

gh auth status

2. Install

git clone <this-repo> github_operation_mcp
cd github_operation_mcp

# Create a virtualenv (any Python 3.11+ works; example uses 3.14)
python3 -m venv .venv
source .venv/bin/activate

# Install the package + its one dependency (mcp SDK, pinned to v1.x)
pip install --upgrade pip
pip install -e .

3. Run the server

Option A — stdio (for Claude Desktop / Claude Code)

python -m github_ops_mcp.server --stdio

You normally don't run this by hand — Claude Desktop launches it for you via the config in step 4.

Option B — HTTP / SSE (for remote clients / demos)

python -m github_ops_mcp.server --http --host 0.0.0.0 --port 8000

The MCP endpoint is then at http://<host>:8000/mcp.

4. Wire it into Claude Desktop

Edit (or create) the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this entry (replace the two paths with your absolute paths):

{
  "mcpServers": {
    "github-ops": {
      "command": "/Users/YOU/Documents/github_operation_mcp/.venv/bin/python",
      "args": ["-m", "github_ops_mcp.server", "--stdio"],
      "env": {
        "WORKSPACE_ROOT": "/Users/YOU/Documents/github_operation_mcp/test_repos"
      }
    }
  }
}

Then fully quit Claude Desktop (Cmd+Q, not just close the window) and reopen it. You should see 25 tools appear under the github-ops server.

WORKSPACE_ROOT — optional. Every clone_repo call lands under this directory as <owner>__<repo>/. If you omit it, the server defaults to a workspace/ folder next to the package.

5. Wire it into Claude Code

Either add the same block to a .mcp.json at the project root, or run:

claude mcp add github-ops \
  /Users/YOU/Documents/github_operation_mcp/.venv/bin/python \
  -- -m github_ops_mcp.server --stdio

6. Try it

In Claude Desktop:

1. "Search for repositories about MCP servers" → search_repos
2. "Give me a full summary of modelcontextprotocol/python-sdk" → generate_repo_summary
3. "Clone octocat/Hello-World" → clone_repo
4. "What branches does it have?" → list_branches
5. "Show me the last 5 commits" → list_commits
6. "Any open PRs on facebook/react?" → list_pull_requests

Tools (25)

• Discovery — search_repos, get_repo_info, summarize_readme
• Repo stats — get_repo_stats, get_contributors, get_language_breakdown, get_topics, get_license, get_releases
• Stretch stats — get_default_branch_protection, get_commit_activity, get_network_info
• Composite — generate_repo_summary
• Setup — clone_repo, pull_latest
• Branches — list_branches, checkout_branch, list_commits, get_file_history
• Comparison — get_status, get_diff, compare_branches
• Issues & PRs — list_open_issues, list_pull_requests, get_pr_diff

Every tool returns { ok: bool, data: ..., error: ... }.

Safety

• All clones live under WORKSPACE_ROOT (./workspace/ by default). Path traversal (../) is blocked.
• git and gh subcommands are whitelisted. Destructive commands (push, reset --hard, rebase, clean, branch -D, gh repo delete/edit, …) raise PermissionError.
• gh api calls are restricted to repos/... endpoints.
• User inputs are passed as argv items, never shell-interpolated (shell=False).
• Auth is not handled by this server — it relies on your existing gh auth login session and git credentials.

Troubleshooting

• Claude Desktop log shows Read-only file system: '/workspace' — you're on an older build; pull latest, the default workspace now anchors to the package directory instead of the CWD.
• Every tool call errors with unexpected keyword argument 'args' — you're on an older build; functools.wraps is now used so FastMCP sees the real parameter names. Pull latest.
• gh: To get started with GitHub CLI, please run: gh auth login — run gh auth login from a terminal, then restart Claude Desktop.
• Server doesn't appear in Claude Desktop — check the log at ~/Library/Logs/Claude/mcp-server-github-ops.log. Common issues: wrong Python path in the config, virtualenv not activated when you ran pip install -e ..

Layout

github_operation_mcp/
├── pyproject.toml
├── README.md
├── plan.md
├── test_repos/                 # cloned repos land here (gitignored)
└── src/github_ops_mcp/
    ├── server.py               # FastMCP app + --stdio/--http entrypoint
    ├── config.py               # WORKSPACE_ROOT, timeouts
    ├── validators.py           # owner_repo + branch name checks
    ├── sandbox.py              # path resolution + traversal guard
    ├── git_wrapper.py          # git subprocess wrapper (whitelist)
    ├── gh_wrapper.py           # gh subprocess wrapper (whitelist)
    └── tools/
        ├── discovery.py
        ├── setup.py
        ├── branches.py
        ├── comparison.py
        ├── issues_prs.py
        ├── repo_stats.py
        ├── repo_stats_ext.py
        └── repo_summary.py