codebase

This MCP server, Codebase Manager, enables Claude, VS Code Copilot, and other MCP-compatible assistants to manage a codebase through natural language. It provides capabilities for complete file system operations (read, write, create, delete, list directories, and secure path validation), advanced Git integration (status checks, branch management, commits with change tracking, diffs, and history), and a command execution engine with a whitelist, built-in test runners, and support for common development tools. It also offers project intelligence features such as dependency analysis, project structure visualization, automated project detection, and real-time project metrics. To use it, configure the server in your Claude Desktop, VS Code, or other MCP-enabled client, supplying the path to your local project so the agent can operate within that workspace. You can issue natural language commands like listing files, reading or editing a file, checking git status, creating branches, running tests, or analyzing dependencies, and the server will translate them into safe, auditable actions against the project.

Prerequisites:

• Python 3.8+ installed on your system
• Git installed for version control features
• A codebase to connect to (your project directory)
• Optional: Claude Desktop or VS Code with MCP integration

Option A: Using UV (Recommended for Python MCP servers)

1. Clone the repository: git clone https://github.com/yourusername/codebase-manager-mcp.git cd codebase-manager-mcp

2. Initialize UV project (if needed by your workflow): uv init --name codebase-mcp-server

3. Install dependencies for MCP CLI access and GitPython: uv add "mcp[cli]" GitPython

4. Run the server for your project: uv run python server.py /path/to/your/project

Option B: Using Pip (traditional Python environment)

1. Clone the repository: git clone https://github.com/yourusername/codebase-manager-mcp.git cd codebase-manager-mcp

2. Create and activate a virtual environment: python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies: pip install "mcp[cli]" GitPython

4. Run the server for your project: python server.py /path/to/your/project

Tips and common notes:

• Environment considerations: Ensure the SERVER has access to your project path and that the path is within allowed boundaries to prevent unauthorized access.
• Command whitelisting: The server uses a safe command whitelist. You can customize ALLOWED_COMMANDS in server.py to permit or restrict additional commands as needed.
• Configuration options: You can run multiple projects by adding multiple entries under mcpServers in your config, each with its own command/args and environment variables.
• Environment variables: Use env to pass project-specific or path variables (e.g., PROJECT_DIR) and adjust PYTHONPATH if you need custom module resolution.
• Troubleshooting: If MCP tooling reports import errors for the mcp package, install via pip install "mcp[cli]" or use UV to add the package as shown in installation steps. For Git operations issues, ensure GitPython is installed. If the server cannot connect to Claude, verify file paths and server startup logs for errors.