RepoMCP

A powerful MCP (Model Context Protocol) server that enables AI agents and LLMs to safely manage GitHub repositories through a feature-branch workflow. It provides a complete set of tools for repository exploration, code editing, and pull request management - all while enforcing branch protection rules.

Why This Exists

This project was built as an alternative to Claude Code. The inspiration came from the limitation that Claude Code does not provide access to Opus 4.5 on the lower tiers(free/pro). By using this MCP server with any MCP-compatible client, you can get Claude Code-like functionality with any model you want, including Opus 4.5.

Think of it as Claude Code, but:

• Works with Opus 4.5 (or any other model)
• Operates through GitHub's API for safer, auditable changes
• Enforces PR-based workflow instead of direct file system access

What is this?

RepoMCP exposes GitHub repository operations as MCP tools that can be used by AI assistants like Claude, GPT, or any MCP-compatible client. It enforces a safe, feature-branch workflow where all changes go through pull requests rather than direct commits to protected branches.

Try It Out

Want to test RepoMCP before deploying your own? Use this live demo server:

MCP Endpoint: https://repo-mcp.vercel.app/mcp

Connected Repository: github.com/areeb1501/InstantMCP

Add the endpoint URL to any MCP-compatible client and start exploring. Any changes you make will create branches and PRs on the demo repository.

Available Tools

Tool	Description
list_branches	List all branches in the repository
create_branch	Create a new feature branch or reuse an existing one
delete_branch	Delete a branch from the repository
get_file	Read file contents and metadata from a specific branch
create_or_update_file	Create a new file or completely rewrite an existing file
patch_file	Apply targeted patches to modify specific sections of a file
delete_file	Delete a file from a feature branch
rename_or_move_file	Rename or move a file to a new location
list_repository_tree	Get complete recursive directory structure
check_file_exists	Check if a file or directory exists
find_files	Find files by name or path pattern
search_file_contents	Search for patterns in file contents using regex
search_code	Advanced code search for functions, classes, imports
get_diff	Get the diff between two branches
list_commits	List recent commits on a branch
get_commit	Get detailed information about a specific commit
list_pull_requests	List pull requests in the repository
get_pull_request	Get detailed information about a specific PR
create_pull_request	Create a pull request from a feature branch
reset_branch_to_commit	Reset a feature branch to a specific commit
revert_file_to_commit	Revert a specific file to its state at a given commit
show_common_workflows	Get step-by-step examples of typical workflows

Use Cases

1. Automated Code Fixes

Let an AI assistant find and fix bugs, typos, or issues across your codebase - all through safe PRs.

2. Documentation Updates

Automatically update README files, add missing documentation, or fix outdated information.

3. Refactoring

Move files, rename modules, and reorganize project structure with AI assistance.

4. Code Reviews & Analysis

Search codebases for patterns, find TODOs, or analyze code structure before making changes.

5. Code Exploration & Understanding

Explore unfamiliar codebases, understand project structure, find function definitions, trace imports, and get up to speed quickly on any repository.

6. Multi-file Feature Implementation

Create new features spanning multiple files with proper branch management.

7. Dependency Updates

Update configuration files, package versions, or environment settings safely.

Problems It Solves

• Safe Repository Access: Blocks direct pushes to protected branches (main, master, production)
• Consistent Workflow: Enforces feature-branch workflow for all changes
• AI-Friendly Operations: Provides structured tools that AI can use reliably
• Efficient Editing: patch_file allows targeted edits without regenerating entire files
• Code Discovery: Search and explore codebases before making changes
• History Management: Revert files or reset branches when needed

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Copy the example environment file and fill in your values:

cp .env.example .env

3. Run the Server

Local development:

python server.py

Or with uvicorn:

uvicorn server:app --reload --port 8000

The MCP endpoint will be available at: http://localhost:8000/mcp

Deployment

Option 1: Deploy to Vercel (Recommended)

The fastest way to get started - deploy in under 5 minutes:

1. Fork/Clone this repository to your GitHub account

2. Go to Vercel and create a new project

3. Import the repository from your GitHub account

4. Add environment variables in the Vercel project settings:

   Variable	Description
   GITHUB_TOKEN	Your GitHub Personal Access Token (create one here)
   REPO_OWNER	Your GitHub username or organization name
   REPO_NAME	The repository you want to manage

5. Deploy - Vercel will automatically build and deploy

6. Start using it - Your MCP endpoint is ready at:

   https://your-project.vercel.app/mcp
   

You can now connect this URL to any MCP-compatible client and start using Opus 4.5 (or any model) with full GitHub repository access.

Option 2: Local Development with ngrok

For local development or testing, expose your localhost using ngrok:

# Terminal 1: Start the server
python server.py

# Terminal 2: Expose with ngrok
ngrok http 8000

ngrok will provide a public URL like https://abc123.ngrok.io. Your MCP endpoint will be at: https://abc123.ngrok.io/mcp

Typical Workflow

1. list_branches()           -> See existing branches
2. create_branch("feature")  -> Create/reuse feature branch
3. get_file("src/app.py")    -> Read existing code
4. patch_file(...)           -> Make targeted edits
5. get_diff("main", "feature") -> Review changes
6. create_pull_request(...)  -> Open PR for review

Requirements

• Python 3.12+
• GitHub Personal Access Token with repo permissions
• FastAPI, FastMCP, and other dependencies (see requirements.txt)

License

MIT