# 🤖 AiderMCP: Aider AI Integration for Claude Desktop & Claude Code

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.0-green.svg)](https://github.com/jlowin/fastmcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

AiderMCP is a **Model Context Protocol (MCP) server** that integrates [Aider](https://github.com/paul-gauthier/aider) AI pair programming into Claude Desktop and Claude Code. Use Aider's powerful code editing capabilities through natural language conversations with Claude.

---

## ✨ Features

- ⚡ **Zero-Install with uvx**: Run directly from GitHub - no cloning or setup required!
- 🚀 **One-Command Setup**: `aider-mcp-server --setup` for manual installation
- 🎯 **Natural Language Interface**: Use Aider through conversational commands
- 🔧 **5 Powerful Tools**: Code improvement, feature addition, bug fixing, refactoring, and status checking
- 🌍 **Cross-Platform**: Works on macOS, Windows, and Linux
- 🔐 **Multi-Provider**: Supports Anthropic, OpenAI, and Google Gemini API keys

---

## 📋 Prerequisites

- **Python 3.11 or 3.12** ([Download](https://www.python.org/downloads/))
  - ⚠️ Python 3.13 not yet supported
- **Claude Desktop** ([Download](https://claude.ai/download))
- **API Key** from at least one provider:
  - [Anthropic](https://console.anthropic.com/)
  - [OpenAI](https://platform.openai.com/api-keys)
  - [Google AI Studio](https://makersuite.google.com/app/apikey) (default)
- **Git** installed and initialized in your project

---

## 🚀 Quick Start with uvx (Recommended)

**The fastest way to use AiderMCP** - no cloning or installation required!

### 1. Add to Claude Desktop Config

Edit your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "aider": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/fuzemobi/AiderMCP.git",
        "aider-mcp-server"
      ],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key-here",
        "ANTHROPIC_API_KEY": "your-anthropic-key-here",
        "OPENAI_API_KEY": "your-openai-key-here"
      }
    }
  }
}
```

**Notes:**
- Add your API keys (at least one: Gemini, Anthropic, or OpenAI)
- If you have other MCP servers, merge this into the existing `mcpServers` object
- If you forked this repo, update the URL to your fork's location

### 2. Restart Claude Desktop

That's it! uvx will automatically:
- Download the repository
- Install all dependencies (aider-chat, fastmcp)
- Start the MCP server

---

## 🔧 Manual Installation (Alternative)

If you prefer manual installation or need to modify the code:

### 1. Install

```bash
# Clone the repository
git clone https://github.com/fuzemobi/AiderMCP.git
cd AiderMCP

# Create virtual environment (Python 3.11 or 3.12)
python3.12 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install
pip install -e .
```

### 2. Set API Keys

```bash
# macOS/Linux
export GEMINI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"  # optional
export OPENAI_API_KEY="your-key-here"     # optional

# Windows PowerShell
$env:GEMINI_API_KEY="your-key-here"
```

### 3. Configure Claude Desktop

```bash
aider-mcp-server --setup
```

### 4. Restart Claude Desktop

**Important:** Restart Claude Desktop for changes to take effect.

---

## 🎮 Basic Usage

### In Claude Desktop or Claude Code

Use natural language to work with Aider:

**Improve Code Quality:**
```
Use aider to improve code quality in src/main.py
```

**Add Features:**
```
Ask aider to add user authentication with JWT tokens
```

**Fix Bugs:**
```
Have aider fix the connection timeout bug in server.py
```

**Refactor Code:**
```
Get aider to refactor the database module for better performance
```

**Check Status:**
```
Use aider to show git status and recent commits
```

---

## 🛠️ Available Tools

| Tool | Description |
|------|-------------|
| **improve_code** | Improve code quality, add type hints, enhance error handling |
| **add_feature** | Add new features to your application |
| **fix_bug** | Fix bugs and issues in your codebase |
| **refactor** | Refactor code for better structure and performance |
| **get_status** | View git status and recent commits |

### Tool Parameters

All tools support these optional parameters:
- **files**: Specific files to work on
- **model**: AI model to use (default: `gemini/gemini-1.5-pro-latest`)
- **auto_commit**: Automatically commit changes (default: `True`)
- **project_path**: Project directory path (default: current directory)

---

## 🏗️ About Aider

[Aider](https://aider.chat/) is an AI pair programming tool that works with your code. It can:
- Edit multiple files at once
- Make coordinated changes across your codebase
- Understand your project structure
- Follow coding conventions and patterns
- Create git commits automatically

AiderMCP makes Aider accessible through Claude's conversational interface, letting you describe what you want in natural language.

---

## 🚨 Troubleshooting

**Tools not appearing in Claude Desktop?**
1. Restart Claude Desktop after running setup
2. Re-run: `aider-mcp-server --setup`
3. Check config file exists:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - Linux: `~/.config/Claude/claude_desktop_config.json`

**Python version errors?**
```bash
python3 --version  # Must be 3.11 or 3.12

# Recreate venv if needed:
rm -rf .venv
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .
```

**API key issues?**
```bash
# Verify keys are set
echo $GEMINI_API_KEY

# Or add to config file manually after running setup
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- [Aider](https://github.com/paul-gauthier/aider) - AI pair programmer
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP framework
- [Anthropic](https://www.anthropic.com/) - Claude and MCP protocol

---

**Made with ❤️ for developers who want AI-powered coding in Claude**