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": "..." } }

---

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.

Variable	Required	Default	Description
GITHUB_TOKEN	yes	—	GitHub Personal Access Token (classic repo scope, or a fine-grained token with read/write on your repos). PERSONAL_GITHUB_TOKEN is accepted as an alias.
GITHUB_USERNAME	no	token owner	Account used to scope searches/repo listing.
EULER_REPOSITORY	no	project-euler	Repo that stores Project Euler solutions.
DEFAULT_VISIBILITY	no	private	Visibility for new repos (private/public).
DEFAULT_BRANCH	no	main	Branch used when initializing new repos.
GIT_AUTHOR_NAME	no	Personal GitHub MCP	Author for local git commits.
GIT_AUTHOR_EMAIL	no	personal-github-mcp@users.noreply.github.com	Committer email for local commits.
LOG_LEVEL	no	INFO	DEBUG, INFO, WARNING, ERROR.
MAX_RESULTS	no	20	Default result cap for list/search tools (1–100).
OPENAI_API_KEY	no	—	Optional OpenAI-compatible API key for LLM-generated READMEs (LLM_API_KEY also accepted).
OPENAI_BASE_URL	no	https://api.openai.com/v1	Base URL for an OpenAI-compatible chat/completions endpoint (LLM_BASE_URL also accepted).
OPENAI_MODEL	no	gpt-4o-mini	Model used for README generation (LLM_MODEL also accepted).

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

Tool	Description
list_repositories(visibility, sort, limit)	List your repos, optionally filtered by private/public and sorted by pushed/updated/created/full_name.
repository_summary(name)	High-level summary: languages, topics, last commit, top-level structure.
create_repository(name, description, private)	Create a repo under your account (auto-initialized with a README).
project_statistics(name)	Language breakdown, commits per author, open issues/PRs.
explain_repository(name)	Plain-language explanation of what a repo is about.
stale_repository_report(threshold_days, limit)	Repos not pushed to for a while.
recommend_project(interests, limit)	Ranked suggestions for what to work on next.

Publishing

Tool	Description
publish_current_project(repo_name, description, private, commit_message, branch)	Publish the current working directory. Detects the project, generates a README and .gitignore when missing, initializes git, creates the GitHub repo if needed, commits and pushes. Returns the repo URL.
publish_project(path, repo_name, description, private, commit_message, branch)	Publish a local directory as a new GitHub repo (init → commit → create repo → push).
backup_project(path, commit_message)	Commit local changes and push to an existing repo (creates the repo only if no remote exists).

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

Search

Tool	Description
search_code(keyword, language, owner, limit)	GitHub code search.
search_repository(name, owner, limit)	GitHub repository search by name.
where_did_i_use(keyword, language, limit)	Find where you used a keyword in your own repos.
search_my_engineering_memory(keyword, limit)	Search across your repositories, README files, architecture documentation, and source code, returning ranked results.

Project Euler

Tool	Description
publish_euler_solution(path, commit_message)	Flagship workflow. Detects the problem in the current directory (folders like 001/ or problem_023/), infers the language and source file, generates a professional README, and uploads the solution + README to your Euler repo.
upload_euler_solution(problem_number, file_path, commit_message)	Upload a solution as problem_<NNN>/<filename> in your Euler repo.
update_progress()	Solved problems, totals, and the next unsolved problem number.

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

Tool	Description
compare_repositories(repository_a, repository_b)	Compare two repos and summarize differences.
dependency_summary(path)	Detect and list a local project's dependencies.
architecture_summary(path)	Languages, structure, and entry points of a local project.

---

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

Area	Placeholder
Claude Desktop tools	docs/screenshots/claude-tools.png
publish_euler_solution result	docs/screenshots/euler-publish.png
Engineering memory search	docs/screenshots/memory-search.png

---

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.