personal-repo-mcp

A self-hosted, multi-repository MCP server for AI agents. It gives an agent a persistent Git workspace on your own VPS, with controlled access to administrator-approved repositories and normal Git operations.

Version 1.0.0 — MVP

Quick install

The quickest way to run the MVP is the Docker Compose deployment described in docs/QUICK_INSTALL.md.

In short:

git clone https://github.com/jsilvanus/personal-repo-mcp.git
cd personal-repo-mcp
cp .env.example .env
mkdir -p config repositories secrets
cp config/repositories.example.json config/repositories.json
printf '%s\n' "$(openssl rand -hex 32)" > secrets/mcp_token
printf '%s\n' 'your-github-pat' > secrets/github_pat
chmod 600 secrets/mcp_token secrets/github_pat
docker compose up -d --build

Before starting the container, edit .env, config/repositories.json, and secrets/github_pat. The MCP token is generated locally above; keep it secret. The default Compose deployment binds the MCP endpoint to 127.0.0.1:8000, so an HTTPS reverse proxy is required for remote access.

For the full production checklist, see docs/DEPLOYMENT.md.

Related MCP server: Coding Tools MCP

Core idea

The administrator controls what repositories the agent may access. The agent controls which allowed repositories it actually clones.

Administrator
    |
    | mcp-config add repo jsilvanus/*
    v
repositories.json (allow-list)
    |
    v
MCP server
    |
    +-- clone_repository("jsilvanus/project")
    |
    v
persistent workspace

The workspace is an ordinary Git repository. GitHub remains an upstream remote; the MCP server is the persistent local workspace and control boundary.

MCP help resources

The server provides modular, MCP-native operational documentation. Start with:

mcp://help/index

Focused topics are available at:

mcp://help/repositories
mcp://help/files
mcp://help/git
mcp://help/chain-command
mcp://help/resources

The help resources are intentionally separate from tools/list: the MCP tool list remains the authoritative API surface, while the help resources provide progressive-disclosure workflow guidance for agents.

Features

• Persistent multi-repository workspaces

• Administrator-controlled repository allow-list

• GitHub PAT authentication for Git operations

• Streamable HTTP transport

• File reads, line-range reads, writes, line edits, search, and patches

• Git status, diff, history, branches, fetch/pull/push, merge/rebase, and conflict handling

• Single-repository chain_command for composing operations

• MCP resources for system, repository, Git, and individual file state

• Resource subscriptions and change notifications

• Secret scrubbing from MCP output

• Git submodule safeguards

• Docker deployment

• Optional hot-git backend for persistent, treeless repository reads and edits

Git backends

The existing Git command backend remains the default compatibility path.

The new hot-git backend can be enabled with:

export PERSONAL_REPO_MCP_GIT_BACKEND=hot-git

The dependency is declared in pyproject.toml and is installed as a normal Python package; it is not a Git submodule.

The backend boundary is deliberately small:

MCP tool
   |
   v
Repository backend
   |
   +-- Git backend
   |
   +-- hot-git backend
          |
          +-- persistent object reader
          +-- treeless object/tree/commit edits
          +-- Git CAS ref publication

When hot-git is selected, each repository gets one lazily-created long-lived backend instance. It is shared by callers and closed with the server. This keeps the persistent cat-file --batch reader alive without creating one process per MCP request.

The first integrated operations are:

• git_read_file — read a file from a ref or commit through the configured backend;

• git_edit — perform a multi-file treeless edit and publish it with an expected-ref CAS.

The existing Git command tools remain available during the migration. Operations that depend on a working tree or Git's higher-level merge/rebase machinery continue to use the compatibility backend.

Chained edits

git_edit returns the resulting commit. A caller can use that commit as the expected base for the next edit:

A(base=X) -> commit A
B(base=A) -> commit B
C(base=B) -> commit C

This is the foundation for integrating the backend with chain_command without allowing concurrent writers to silently overwrite each other.

Deployment

Configure the host with mcp-config, then start the single Docker deployment:

mcp-config pat
mcp-config add repo jsilvanus/*
docker compose up -d --build

mcp-config add repo changes only the administrator allow-list. It does not clone repositories. The agent clones an allowed repository through the MCP when needed.

For hot-git mode, the normal Python dependency installation installs the library. No submodule checkout is required.

See docs/QUICK_INSTALL.md for the shortest setup path and docs/DEPLOYMENT.md for persistent storage, credentials, HTTPS, and configuration details.

License

EUPL-1.2