Skip to main content
Glama
Personal GitHub MCP

Personal GitHub MCP

by sam170203

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

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.

Available Tools

20 tools
architecture_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

    B3.2/5.0

    Scored across 20 tools

    Disambiguation2/5

    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 Consistency2/5

    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.

    Tool Count3/5

    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.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to automate GitHub repository management, issue tracking, and commits using natural language.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      -