Personal GitHub MCP

A production-grade Model Context Protocol server that acts as a personal GitHub engineering assistant.

Instead of exposing raw GitHub API calls, it provides high-level tools that represent real user intentions — publish the project you are working in, upload a Project Euler solution with an auto-generated README, find where you used a library, or search your entire engineering memory.

Built with Python 3.12+, the official MCP Python SDK (v2), PyGithub, GitPython, Pydantic v2, and uv.

Features

• Repository management — list, summarize, create, and inspect your repositories.

• Publishing — publish_current_project publishes the directory you are in with an auto-generated README and .gitignore; publish_project / backup_project cover the rest.

• Project Euler flagship workflow — publish_euler_solution detects the problem from the current directory, infers the language, generates a professional README (LLM or static analysis), and pushes both to your solutions repo.

• Search — GitHub code/repo search plus search_my_engineering_memory, which ranks hits across your repositories, READMEs, architecture docs, and source code.

• Analysis — explain a repo in plain language, compare repos, recommend what to work on, detect stale repos, and summarize a local project's dependencies and architecture.

• Structured, typed errors — the server never crashes; every failure is returned as a structured envelope.

• Structured JSON logging with per-tool timing.

Every tool returns the same envelope:

{ "ok": true, "data": { ... } }

or

{ "ok": false, "error": { "kind": "repository_not_found", "message": "..." } }

Related MCP server: git-steer

Architecture

src/
├── server.py              # MCP server assembly + tool registration wiring
├── main.py                # CLI entry point (uv run personal-github-mcp)
├── config.py              # Settings loaded from .env (pydantic-settings)
├── models.py              # Pydantic response models for every tool
├── github_client.py       # Thin PyGithub wrapper (exception mapping)
├── git_client.py          # Thin GitPython wrapper (exception mapping)
├── dependencies.py        # Service container / dependency wiring
├── tools/                 # Tool registration only (thin, one concern per file)
│   ├── repo.py            #   repository listing/summary/create + reporting
│   ├── publish.py         #   publish_project, publish_current_project, backup_project
│   ├── search.py          #   search_code, search_repository, where_did_i_use,
│   │                      #   search_my_engineering_memory
│   ├── euler.py           #   upload_euler_solution, publish_euler_solution, update_progress
│   └── analyze.py         #   compare_repositories, dependency_summary, ...
├── services/              # Business logic (SOLID, no raw API calls here)
│   ├── github_service.py  #   core GitHub CRUD (list/summary/create/exists)
│   ├── report_service.py  #   statistics, explain, stale report, recommend, compare
│   ├── git_service.py     #   local git + project analysis
│   ├── search_service.py  #   code/repo search + engineering memory search
│   ├── euler_service.py   #   Project Euler detection, upload, publish, progress
│   ├── project_service.py #   publish / backup workflows
│   ├── readme_service.py  #   README generation (static analysis + optional LLM)
│   ├── scaffold_service.py#   README + .gitignore scaffolding for projects
│   └── llm_service.py     #   optional OpenAI-compatible client (never required)
└── utils/
    ├── logging.py         # Structured JSON logging
    └── errors.py          # Typed errors + tool_handler decorator

Layering is strict:

tools (MCP registration only)
   → services (business logic, returns Pydantic models)
      → clients (PyGithub / GitPython wrappers, raise typed errors)
         → utils (shared errors + logging)

This keeps tool files small, makes the business logic unit-testable, and keeps the server module free of implementation details. Services are dependency-injected and model-backed so they can be lifted straight into LangGraph agents later.

Installation

Prerequisites: Python 3.12+, git, and uv.

git clone <your-repo-url> personal-github-mcp
cd personal-github-mcp

# Install dependencies and the package (editable dev install)
uv sync --all-extras

# Configure secrets
cp .env.example .env
# edit .env and set GITHUB_TOKEN

Configuration

Copy .env.example to .env and fill in at least GITHUB_TOKEN.

Never commit .env. It is git-ignored. If the token is missing at startup the server prints a clear message and exits with a non-zero code.

README generation never fails without an LLM. When no OPENAI_API_KEY is set (or the call fails), READMEs are generated deterministically from static analysis of the project/solution.

Tools

Repository

Publishing

Publishing handles every combination: existing repos, not-yet-created repos, repos with a remote, and repos without one.

Search

Project Euler

Generated Euler READMEs include: Problem Number, Problem Statement (placeholder — the official statement is copyright and cannot be reproduced), Approach, Complexity (time & space), Key Insights, and Files.

Analysis

Example usage

// publish the project you're currently in (detects cwd, writes README + .gitignore)
publish_current_project(description: "my notes app")
// → { "ok": true, "data": { "repository": "me/notes-app", "url": "https://github.com/me/notes-app",
//     "created": true, "readme_generated": true, "gitignore_generated": true, ... } }

// flagship Project Euler workflow (run from inside "ProjectEuler/023/")
publish_euler_solution()
// → { "ok": true, "data": { "problem_number": 23, "path_in_repo": "problem_023/solution.py",
//     "readme_url": "https://github.com/me/project-euler/...", ... } }

// search your entire engineering memory
search_my_engineering_memory(keyword: "sieve")
// → { "ok": true, "data": { "query": "\"sieve\" user:me", "items": [
//     { "kind": "repository", "repository": "me/algo", ... },
//     { "kind": "source", "repository": "me/algo", "path": "sieve.py", ... } ] } }

// publish a local project by path
publish_project(path: "/Users/me/projects/notes", repo_name: "notes", private: true)
// → { "ok": true, "data": { "repository": "me/notes", "url": "https://github.com/me/notes", "created": true, ... } }

// upload a Project Euler solution
upload_euler_solution(problem_number: 25, file_path: "/Users/me/euler/p025.py")
// → { "ok": true, "data": { "problem_number": 25, "path_in_repo": "problem_025/p025.py", ... } }

Connecting from Claude Desktop

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

{
  "mcpServers": {
    "personal-github-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/personal-github-mcp", "run", "personal-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

If your token is already in the project's .env, you can omit env — the server loads .env itself.

Connecting from Cursor

In Cursor, add an MCP server (Settings → MCP) with the stdio type:

{
  "mcpServers": {
    "personal-github-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/personal-github-mcp", "run", "personal-github-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

The same pattern works for other MCP clients (Claude Code, VS Code Copilot, etc.): point the client at uv --directory <path> run personal-github-mcp.

Screenshots

Troubleshooting

"GitHub token is required" and the server exits with code 2 Set GITHUB_TOKEN in .env (or export it) and retry. The server deliberately refuses to start without a token.

publish_euler_solution says "No Project Euler problem detected" The tool expects to run inside (or above) a folder named like 001, problem_023, or ProjectEuler/023, and that folder must contain a recognized source file (solution.py, main.cpp, etc.). Supported extensions: .py, .cpp, .cc, .cxx, .c, .rs, .go, .js, .ts, .java, .rb, .cs, .php, .swift, .kt, .hs, .lua, .zig, .ml.

"Git push failed" A remote may point to a repository you cannot write to, or the branch has diverged. Run git remote -v and git log to diagnose; backup_project is the safe way to push to an existing remote.

GitHub API / rate-limit errors GitHub rate limits apply. Wait and retry, or reduce limit/MAX_RESULTS. Fine-grained tokens need read/write access to the repos you manage.

READMEs look generic No LLM is configured, so READMEs come from static analysis. Set OPENAI_API_KEY (and optionally OPENAI_BASE_URL/OPENAI_MODEL) to get LLM-written READMEs. Any LLM failure falls back to static analysis silently.

Logs are JSON lines Set LOG_LEVEL=DEBUG for more detail. Per-tool timing and error kinds are logged to stderr.

Testing

uv run pytest

The suite covers GitHub services (with in-memory fakes), reporting/analysis services, git services (real repos in temp dirs, including pushes to a local bare remote), the full publish/backup workflows, Project Euler detection and publishing, README/.gitignore scaffolding, search, MCP tool registration and response envelopes.

Development

uv sync --all-extras        # install everything
uv run ruff format src tests
uv run ruff check src tests
uv run pytest

Roadmap

• LangGraph integration — services are deliberately dependency-injected and model-backed so they can be lifted straight into LangGraph agents/nodes.

• Project Euler templates — generate solution scaffolds per problem.

• PR automation — raise pull requests from local branches.

• SSE / HTTP transport — support transport="streamable-http" for remote clients.

• Issues triage — list and label open issues across repositories.

• Auth UX — OAuth device flow as an alternative to a PAT.

• Fuzzy "where did I use" — tokenized search across clone history, not just the API.