Personal GitHub MCP
Provides tools for interacting with GitHub, enabling repository management (list, create, summarize), project publishing, code and repository search, repository analysis and comparison, and uploading Project Euler solutions to a dedicated repository.
Provides optional integration with OpenAI-compatible APIs for generating README files for projects and Project Euler solutions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Personal GitHub MCP publish current project to my GitHub"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_projectpublishes the directory you are in with an auto-generated README and.gitignore;publish_project/backup_projectcover the rest.Project Euler flagship workflow —
publish_euler_solutiondetects 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: GitHub Agent MCP Server
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 decoratorLayering 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_TOKENConfiguration
Copy .env.example to .env and fill in at least GITHUB_TOKEN.
Variable | Required | Default | Description |
| yes | — | GitHub Personal Access Token (classic |
| no | token owner | Account used to scope searches/repo listing. |
| no |
| Repo that stores Project Euler solutions. |
| no |
| Visibility for new repos ( |
| no |
| Branch used when initializing new repos. |
| no |
| Author for local git commits. |
| no |
| Committer email for local commits. |
| no |
|
|
| no |
| Default result cap for list/search tools (1–100). |
| no | — | Optional OpenAI-compatible API key for LLM-generated READMEs ( |
| no |
| Base URL for an OpenAI-compatible |
| no |
| Model used for README generation ( |
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_KEYis set (or the call fails), READMEs are generated deterministically from static analysis of the project/solution.
Tools
Repository
Tool | Description |
| List your repos, optionally filtered by |
| High-level summary: languages, topics, last commit, top-level structure. |
| Create a repo under your account (auto-initialized with a README). |
| Language breakdown, commits per author, open issues/PRs. |
| Plain-language explanation of what a repo is about. |
| Repos not pushed to for a while. |
| Ranked suggestions for what to work on next. |
Publishing
Tool | Description |
| Publish the current working directory. Detects the project, generates a README and |
| Publish a local directory as a new GitHub repo (init → commit → create repo → push). |
| 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 |
| GitHub code search. |
| GitHub repository search by name. |
| Find where you used a keyword in your own repos. |
| Search across your repositories, README files, architecture documentation, and source code, returning ranked results. |
Project Euler
Tool | Description |
| Flagship workflow. Detects the problem in the current directory (folders like |
| Upload a solution as |
| 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 two repos and summarize differences. |
| Detect and list a local project's dependencies. |
| 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 |
|
|
|
Engineering memory search |
|
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 pytestThe 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 pytestRoadmap
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.
Available Tools
20 toolsarchitecture_summaryA
Summarize the architecture of a local project.
Reports file language breakdown, top-level structure, and likely entry points.
Args: path: absolute path to the local project directory.
Inputs: path (required). Returns: object
backup_projectA
Commit local changes and push them to GitHub.
Requires path to be a git repository with (or able to create) an
'origin' remote. Use for routine backups of an existing project.
Args: path: absolute path to the local project directory. commit_message: optional commit message (defaults to a dated message).
Inputs: path (required), commit_message. Returns: object
compare_repositoriesA
Compare two repositories and summarize their differences.
Args: repository_a: first repository name ('repo' or 'owner/repo'). repository_b: second repository name ('repo' or 'owner/repo').
Inputs: repository_a (required), repository_b (required). Returns: object
create_repositoryA
Create a new repository on GitHub under your account.
Args: name: desired repository name (letters, digits, '-', '_', '.'). description: short description shown on GitHub. private: whether the repository is private.
Inputs: name (required), private, description. Returns: object
dependency_summaryA
Summarize the dependencies of a local project.
Detects a manifest file (pyproject.toml, requirements.txt, package.json, Cargo.toml, go.mod, Gemfile, composer.json) and lists its dependencies.
Args: path: absolute path to the local project directory.
Inputs: path (required). Returns: object
explain_repositoryB
Explain what a repository is about in plain language.
Args: name: repository name ('repo' or 'owner/repo').
Inputs: name (required). Returns: object
list_repositoriesA
List your GitHub repositories.
Args: visibility: 'all', 'private' or 'public'. sort: 'pushed', 'updated', 'created' or 'full_name'. limit: maximum number of repositories to return.
Inputs: sort, limit, visibility. Returns: object
project_statisticsA
Show development statistics for a repository.
Includes language breakdown, commit counts per author, and open issues / pull requests.
Args: name: repository name ('repo' or 'owner/repo').
Inputs: name (required). Returns: object
publish_current_projectA
Publish the current working directory as a GitHub repository.
Detects the project, generates a README and .gitignore when missing, initializes git if needed, creates the GitHub repository if needed, commits and pushes everything, then returns the repository URL.
Args: repo_name: GitHub repository name (defaults to the folder name). description: short description for the new repository. private: whether the repository is private. commit_message: optional commit message for the initial commit. branch: default branch for new repositories.
Inputs: branch, private, repo_name, description, +1 more. Returns: object
publish_euler_solutionA
Publish a Project Euler solution with an auto-generated README.
Detects the problem in the current directory (or path), infers the
problem number, language and source file, generates a README.md, then
uploads the solution and README to your Euler repository and returns
the GitHub URL.
Args: path: optional directory containing the problem (defaults to the current working directory). commit_message: optional commit message.
Inputs: path, commit_message. Returns: object
publish_projectA
Publish a local project as a new GitHub repository.
Initializes a git repository if needed, commits all files, creates the remote repository on GitHub and pushes the default branch.
Args: path: absolute path to the local project directory. repo_name: GitHub repository name (defaults to the folder name). description: short description for the new repository. private: whether the repository is private. commit_message: optional commit message for the initial commit. branch: default branch for new repositories.
Inputs: path (required), branch, private, repo_name, +2 more. Returns: object
recommend_projectA
Recommend a project to work on next.
Scores your repositories by recency, activity and (optionally) a comma-separated list of interests matched against the primary language.
Args: interests: comma-separated language interests, e.g. 'python, rust'. limit: number of recommendations to return.
Inputs: limit, interests. Returns: object
repository_summaryB
Return a high-level summary of a GitHub repository.
Args: name: repository name ('repo' or 'owner/repo').
Inputs: name (required). Returns: object
search_codeA
Search GitHub code for a keyword.
Args: keyword: the text to search for. language: optional filter, e.g. 'python'. owner: optional GitHub user/org to scope the search to. limit: maximum number of results.
Inputs: keyword (required), limit, owner, language. Returns: object
search_my_engineering_memoryA
Search your engineering memory across all of your repositories.
Looks through repository metadata, README files, architecture documentation and source code, returning ranked results.
Args: keyword: the text to search for. limit: maximum number of ranked results to return.
Inputs: keyword (required), limit. Returns: object
search_repositoryA
Search for repositories by name.
Args: name: repository name to search for. owner: optional GitHub user/org to scope the search to. limit: maximum number of results.
Inputs: name (required), limit, owner. Returns: object
stale_repository_reportA
List repositories that have not been pushed to recently.
Args: threshold_days: only report repos idle for at least this many days. limit: maximum number of repos to report.
Inputs: limit, threshold_days. Returns: object
update_progressA
Report your current Project Euler progress from GitHub.
Returns the list of solved problems, totals and the next unsolved problem number.
Inputs: no named parameters. Returns: object
upload_euler_solutionB
Upload a Project Euler solution to your solutions repository.
Files are stored as problem_<NNN>/<filename> in the Euler
repository (default: project-euler).
Args: problem_number: the Project Euler problem number. file_path: absolute path to the local solution file. commit_message: optional commit message.
Inputs: file_path (required), problem_number (required), commit_message. Returns: object
where_did_i_useA
Find where you used a given keyword in your own repositories.
Args: keyword: the text to search for in your code. language: optional filter, e.g. 'python'. limit: maximum number of results.
Inputs: keyword (required), limit, language. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Several tools have overlapping purposes: repository_summary, explain_repository, and project_statistics all describe repository characteristics; publish_project and publish_current_project both publish local projects; and search_code, where_did_i_use, and search_my_engineering_memory all perform search operations. These unclear boundaries make it difficult for an agent to reliably select the correct tool.
Naming is mixed between verb-first (list_repositories, create_repository, search_code) and noun-first (repository_summary, project_statistics, dependency_summary) patterns, with the exception of 'where_did_i_use' which uses a completely different sentence-like format. The inconsistency is significant enough to hinder predictable tool selection.
With 20 tools, the server is on the heavy side—slightly above the ideal 3–15 range. While the count is not outrageous, the many overlapping tools inflate the number and make the set feel heavier than it needs to be.
The server covers repository listing, creation, searching, publishing, and local project analysis, but lacks basic GitHub operations such as updating or deleting repositories, managing issues and pull requests, or viewing commit history. These are significant gaps for a GitHub-related MCP, leaving core workflows incomplete.
Maintenance
Related MCP Connectors
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Ask any GitHub repository a question. Get source-backed answers.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage GitHub repositories, branches, issues, pull requests, releases, and actions through natural language.6MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with GitHub via natural language, supporting repository management, issue tracking, file commits, and more.ISC
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to automate GitHub repository management, issue tracking, and commits using natural language.-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to answer natural-language GitHub queries by listing repositories, issues, pull requests, branches, commits, and files, as well as performing writes with dry-run and confirmation safeguards.-