Aider Executor MCP server

Project Information

stdio MCP server to run aider as a detached background process with basic git tools and status checks. This allows LLMs to start code editing processes freely and check the aider chat history for progress at a later time to allow for agentic swarm behavior.

An .aider.mcp.details.json file is created in the same directory with the process ID and starting datetime. The MCP server provides tools for LLM agents to check if the process is still running, and to check the .aider.chat.history.md for updates.

The original message prompt send via the MCP server to aider is also recorded in .aider.mcp.prompt.txt.

Quick Start

You can run the server directly using npx, passing in environment variables for the endpoint URL and API keys. Provide --whitelist arguments with a permitted glob path otherwise all operations will be denied by default.

{
  "mcpServers": {
    "mcp-aider-executor": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-aider-executor",
        "--whitelist",
        "/home/user/my-project/**",
        "--whitelist",
        "/local/my-application/**"
      ],
      "env": {
        "AIDER_MODEL": "openai/gemma-4-E4B-it-IQ4_XS",
        "OPENAI_API_BASE": "http://127.0.0.1:1337/v1",
        "OPENAI_API_KEY": "your-key-here"
      }
    }
  }
}

Prompting

You can directly tell your LLM to use Aider by providing them with a directory to work in. For example:

Use Aider to create a simple Python hello world console application in "/home/my-project"

For extra Aider options, you should set it properly using environment variables (the env in MCP settings .json), or ask your LLM to create the Aider YAML configuration file for you in the project directory. By default, the server comes with some basic git and file tools to allow the LLM to look around. These tools can be disabled via the options below if you'd like to use a separate MCP server to handle more advanced functions.

[!CAUTION]

For security purposes, the MCP server does not have the functionality to write API keys into the configuration YAML.

Use env instead to provide keys like OPENAIAPIKEY. Don't tell your LLM about it.

Options

You can add these arguments in the npx command.

-h, --help                     Display this message
--model <model>                Default LLM main model override (i.e. always use this model no matter what)
--edit-format <format>         Main model edit format override, regardless of config or LLM inference
--architect                    Always run in architect mode (--no-architect for never)
--editor-model <model>         Default secondary editor model override for architect mode
--editor-edit-format <format>  Editor model's edit format override
--no-add-message-notes         Disables the adding of aider-specific notes to message prompts
--no-register-git-tools        Disables registration of all git tools for this server
--no-allow-git-edits           Disables only the git tools which modify the repo history
--no-register-file-tools       Disables registration of wide file access tools for this server
--whitelist <path>             Only allow operations within the glob path

Environment Prerequisites

The environment running the MCP server must have the following tools installed and available as executable commands in the shell:

1. node
2. aider
3. git

[!WARNING]

You should set the number of parallel requests to 2 if you are using the same local endpoint for aider,

otherwise your chat session and the background aider process will be stuck waiting for each other.

You should also set the OPENAIAPIKEY environment variable to a non-empty value if you are using a local

OpenAI-compatible endpoint because aider requires it even if you don't use an API key.

You still need the openai/ prefix when specifying model names for local endpoints in aider.

Shortened. The full README is on GitHub.