aider mcp server

A Model Context Protocol (MCP) server that allows Claude and other MCP clients to connect to Aider for efficient file editing capabilities.

Overview

This MCP server bridges the gap between AI assistants like Claude and Aider's powerful file editing capabilities. It provides a standardized interface through the Model Context Protocol, allowing Claude to:

• Edit existing files using Aider's capabilities
• Create new files with content
• Extract code blocks from markdown text
• Get git status information
• Check Aider installation status
• Access and use Aider's configuration system

Prerequisites

• Python 3.8 or higher
• Aider installed (pip install aider-chat)
• An API key for OpenAI or Anthropic (depending on which model you want Aider to use)
• Git repository for file editing

Installation

You can install the Aider MCP server in several ways:

Using UV (Recommended)

If you have uv installed:

# Install uv if you do not have it
curl -fsSL https://astral.sh/uv/install.sh | bash

# Run directly with uvx (no installation required)
uvx aider-mcp

Using PIP

# Install the package
pip install aider-mcp

# Run the server
aider-mcp

Usage

The Aider MCP server runs in MCP protocol mode over stdio by default, which is designed for direct integration with MCP clients like Claude Desktop and Cursor IDE.

# Run directly with uvx (recommended)
uvx aider-mcp

# With repository path specified
uvx aider-mcp --repo-path=/path/to/your/repo

# With custom Aider executable path
uvx aider-mcp --aider-path=/path/to/aider

# With environment variables
REPO_PATH=/path/to/your/repo uvx aider-mcp

Command Line Options

You can customize the server with these environment variables or command-line arguments:

• --aider-path: Path to the Aider executable (default: "aider", automatically searches PATH)
• --repo-path: Path to the git repository (default: current directory)
• --config-file: Path to a custom Aider config file
• --env-file: Path to a custom .env file
• --verbose, -v: Enable verbose output

Client Configuration

Claude Desktop

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "aider-mcp": {
      "command": "uvx",
      "args": [
        "aider-mcp",
        "--repo-path", "/path/to/your/repo"
      ]
    }
  }
}

Cursor IDE

To integrate with Cursor IDE:

1. Open Cursor Settings
2. Navigate to Features > MCP Servers
3. Click Add new MCP server
4. Enter this configuration:

   name: aider-mcp
   type: command
   command: uvx aider-mcp --repo-path=/path/to/your/repo

5. After configuring, ensure you're in Agent mode in the Composer to use MCP tools

Aider Configuration Support

This MCP server supports Aider's configuration system, allowing you to:

1. Use configuration from .aider.conf.yml files in:
2. Your home directory
3. The git repository root
4. The current directory

5. A custom path specified with --config-file

6. Use environment variables from .env files in:

7. Your home directory
8. The git repository root
9. The current directory

10. A custom path specified with --env-file

11. Pass custom Aider options when editing files through the MCP tools.

Example Prompts for Claude

Once connected to Claude, you can use prompts like:

• "Edit my app.py file to add error handling to the main function"
• "Create a new file called utils.py with helper functions for date formatting"
• "Show me the current git status of the repository"
• "Extract the Python code from this explanation and save it to a file"

Available Tools

The MCP server provides these directory-based tools:

• edit_files: Make targeted code changes in a specified directory
• Requires a directory path and detailed instructions
• Automatically accepts all proposed changes (uses --yes-always)

• Additional Aider options can be specified when needed

• create_files: Create new files with content in a specified directory

• You can provide multiple files to create at once

• Optionally commit the new files to git

• git_status: Get git status of a specified directory's repository

• Quick way to check for modified, added, deleted, and untracked files

• extract_code: Extract code blocks from markdown or text

• Can optionally save extracted code blocks to files in a specified directory

• Preserves language information from code block markers

• aider_status: Check Aider installation and environment status

• Verifies Aider is correctly installed and accessible
• Can check specific directories for configuration

• Reports on API keys and environment variables

• aider_config: Get detailed Aider configuration information

• Shows which configuration files are being used
• Displays settings from all layers of configuration
• Reports available environment variables

Environment Variables

The server uses environment variables which can be set directly or through .env files:

• AIDER_PATH: Path to the Aider executable
• REPO_PATH: Path to the git repository
• AIDER_CONFIG_FILE: Path to a custom Aider config file
• AIDER_ENV_FILE: Path to a custom .env file
• AIDER_MCP_VERBOSE: Enable verbose logging
• OPENAI_API_KEY: Your OpenAI API key (if using GPT-4 with Aider)
• ANTHROPIC_API_KEY: Your Anthropic API key (if using Claude with Aider)

Debugging

You can use the MCP inspector to debug the server:

# Test with MCP inspector
npx @modelcontextprotocol/inspector uvx aider-mcp

# Test with specific repository path
npx @modelcontextprotocol/inspector uvx aider-mcp --repo-path=/path/to/your/repo

# If running from Python package
npx @modelcontextprotocol/inspector python -m aider_mcp

The inspector provides an interactive UI to: 1. View available tools and their schemas 2. Call tools with test parameters 3. See the responses and debug issues

Development

For local development:

git clone https://github.com/yourusername/aider-mcp-server.git
cd aider-mcp-server
pip install -e .

License

Unlicense