MCP Codebase Browser

A Python-based Model Context Protocol (MCP) server that gives Claude full access to your codebase for file management, code editing, searching, and direct shell command execution.

This server was created with assistance from Claude and prioritizes simplicity and compatibility with Claude's natural working style.

Overview

The Codebase Browser is a lightweight MCP tool that combines file operations, code editing, search, backups, and CLI command execution into a single unified interface. It works with both Claude Desktop (via stdio) and browser-based Claude (via SSE/HTTP).

Key Features:

• File operations (read, write, delete, move, copy, mkdir, rmdir)
• Code editing with find/replace operations
• Full-text search across your codebase
• Automatic backups and restoration
• Shell command execution with commit tracking (new)
• Automatic operation history and commit tracking
• Two deployment modes: Claude Desktop (stdio) and Web/Browser (SSE)

Requirements

Core

• Python 3.8 or higher
• Claude Desktop app OR browser-based Claude with MCP support

OS Support

• Windows, macOS, Linux
• Shell: cmd, PowerShell, bash, zsh (auto-detected)

Installation

Quick Install (Claude Desktop)

Run setup.bat (Windows) or the equivalent shell script to automatically:

• Create a Python virtual environment
• Install required dependencies
• Set up a Project directory
• Detect your OS and available shells
• Generate CLI configuration
• Display Claude Desktop configuration instructions

Manual Installation

Create virtual environment:

python -m venv mcp_env
source mcp_env/bin/activate  # On Windows: mcp_env\Scripts\activate

Install dependencies:

pip install mcp

Create Project directory:

mkdir Project

Configure Claude Desktop: Open claude_desktop_config.json and add:

{
  "mcpServers": {
    "MCP_Codebase_Browser": {
      "command": "/path/to/your/mcp_env/bin/python",
      "args": ["/path/to/your/codebase_server.py"]
    }
  }
}

Usage

With Claude Desktop

1. Complete setup above
2. Place your codebase in the Project directory
3. Restart Claude Desktop
4. Look for the hammer icon in the chat input box
5. Claude can now manage your codebase

File Operations Examples

• "List all files in the project"
• "Read the content of src/main.py"
• "Create a new file called utils.js"
• "Search for all uses of 'import' in the codebase"
• "Edit this function and add error handling"
• "Create a backup of my project"
• "Restore from the backup named 'my_project_backup'"

CLI Command Examples (NEW)

• "Run npm install to set up dependencies"
• "Execute the test suite with pytest"
• "Compile the code using gcc"
• "Check the git status"
• "Build the project with cargo build"

When you ask Claude to run a command, he provides a message describing what he's doing, and the command is tracked in your operation history.

Deployment Modes

1. Claude Desktop (stdio)

Best for: Local development with Claude Desktop app

• Direct connection via stdio
• Automatic shell detection
• No network exposure
• Simplest setup

Use: Follow the installation steps above

2. Web/Browser Claude (SSE Mode)

Best for: Using Codebase Browser from claude.ai in the browser

The SSE version lets you connect Claude on the web (claude.ai) to your local codebase over the internet via a secure tunnel.

How it works: codebase_server_sse.py runs a local HTTP server. start_tunnel.bat exposes it publicly via serveo.net — a free SSH tunneling service that requires no account or installation, just standard SSH. Your server becomes accessible at https://yoursubdomain.serveo.net/sse, which you add as a custom connector in Claude.

1. Configure your .env

Copy .env.example to .env and set your subdomain and port:

TUNNEL_SUBDOMAIN=yoursubdomainhere
SSE_PORT=9051

The subdomain is first-come, first-served — if it's not currently in use you get it. Pick something unique enough that nobody else will grab it. If it's taken you'll see an error in the tunnel window and just need to pick a different name.

2. Run start_tunnel.bat

This opens two windows — one running the MCP server, one running the SSH tunnel to serveo.net. When the tunnel is up you'll see:

Forwarding HTTP traffic from https://yoursubdomainhere.serveo.net

3. Add as a connector in Claude

Go to Claude.ai → Settings → Connectors → Add custom connector and enter your full SSE URL:

https://yoursubdomainhere.serveo.net/sse

Notes:

• Serveo handles HTTPS automatically — no SSL cert setup needed
• Your subdomain isn't reserved — if your tunnel is down someone else could claim it. Just pick a new name in .env if that happens
• For a guaranteed persistent subdomain you'd need to own a domain and add DNS records pointing to serveo.net — see serveo.net docs

Configuration

CLI Configuration (Auto-generated)

When you run setup.bat, a cli_config.json is created that tells Claude:

• Your OS type
• Available shells (cmd, PowerShell, bash, zsh, etc.)
• How to invoke commands

SSE Configuration (.env)

For the SSE version, copy .env.example to .env and configure your settings. At minimum set TUNNEL_SUBDOMAIN to use start_tunnel.bat.

Important: Never commit .env to version control (it's in .gitignore)

Safety & Best Practices

File Size Limits

• Large files are read/returned with line number filtering to prevent context overflow
• Files over 10MB are skipped during search operations
• Result sizes are capped at ~99KB to maintain response efficiency

Commit Tracking

• Every operation (file writes, edits, deletes, CLI commands) is logged with intent
• View operation history with: "Show me recent commits"
• Use backups before major operations

Backups

• Create backups: "Backup my codebase named 'v1.0'"
• List backups: "Show me my backups"
• Restore: "Restore from backup named 'v1.0'"

⚠️ WARNING

This tool allows Claude to make changes to your files. He will probably break things.

This is a powerful tool. Always ask Claude to create backups before major changes. The author takes no responsibility for data loss.

Troubleshooting

• Claude doesn't show the hammer icon: Restart Claude Desktop and check that claude_desktop_config.json has correct paths
• Command execution fails: Check that your shell is in the detected shells (check cli_config.json)
• Logs: Check Claude Desktop logs at %AppData%\Claude\logs\mcp*.log (Windows) or ~/.claude/logs/ (macOS/Linux)
• Path issues: Ensure paths use forward slashes on macOS/Linux, backslashes on Windows
• SSL errors (SSE): Verify certificate paths in .env are correct

Notes

• Single unified tool: Everything is one tool to minimize permission prompts
• No artificial restrictions: Claude works intuitively with the tool rather than against engineered limitations
• Language agnostic: Works with any programming language (JavaScript, Python, Java, Rust, Go, etc.)
• Context efficiency: File operations intelligently handle size to prevent context bloat
• Operation history: Every change is tracked for accountability and debugging

Design Philosophy

This tool embraces Claude's strengths rather than fighting his weaknesses.

Other MCP tools try to "teach" Claude through restrictive error messages or puzzles. In practice, Claude doesn't learn well from tool constraints—he just moves on to a different approach. Instead, this tool works with Claude's actual behavior:

• Code awareness: Claude maintains an excellent mental model of your code. The tool leverages this by accepting his descriptions of changes ("find X, replace with Y") rather than forcing line numbers.
• Intent clarity: Every operation requires a message describing intent. This makes changes auditable and helps Claude stay focused.
• Simplicity: No artificial barriers, just direct file access and command execution.
• History: Full commit tracking so you can understand what happened and why.

The result: minimal tool use failures and maximum productivity.

License

MIT License - See LICENSE file for details