{"id":30870092,"url":"https://github.com/larock22/aider-mcp","last_synced_at":"2026-05-13T22:36:37.643Z","repository":{"id":313695825,"uuid":"995574587","full_name":"larock22/aider-mcp","owner":"larock22","description":"WebSocket server that exposes Aider's AI coding capabilities through the Model Context Protocol (MCP) for programmatic access","archived":false,"fork":false,"pushed_at":"2025-06-03T17:33:50.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-17T03:03:07.558Z","etag":null,"topics":["ai-coding","aider","mcp-server","model-context-protocol","openai","typescript","websocket"],"latest_commit_sha":null,"homepage":"https://aider.chat","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/larock22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-03T17:33:48.000Z","updated_at":"2025-06-03T17:36:15.000Z","dependencies_parsed_at":"2025-11-17T03:01:42.408Z","dependency_job_id":null,"html_url":"https://github.com/larock22/aider-mcp","commit_stats":null,"previous_names":["larock22/aider-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/larock22/aider-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larock22%2Faider-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larock22%2Faider-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larock22%2Faider-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larock22%2Faider-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/larock22","download_url":"https://codeload.github.com/larock22/aider-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/larock22%2Faider-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33002973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"ssl_error","status_checked_at":"2026-05-13T13:14:51.610Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","aider","mcp-server","model-context-protocol","openai","typescript","websocket"],"created_at":"2025-09-07T22:04:30.847Z","updated_at":"2026-05-13T22:36:37.636Z","avatar_url":"https://github.com/larock22.png","language":"TypeScript","funding_links":[],"categories":["🤖 AI/ML"],"sub_categories":[],"readme":"# Aider MCP WebSocket Server\n\n## Quick Start\n\nThis is a **real MCP (Model Context Protocol) server** that lets you control Aider programmatically via WebSocket. It's like having Aider as an API.\n\n```bash\n# 1. Install\nnpm install\ncp .env.example .env\n# Add your OPENAI_API_KEY=sk-... to .env\n\n# 2. Run the MCP server (recommended)\nnpm run mcp\n\n# 3. Test it\npython3 test-debug.py\n```\n\n**What you get**: Send natural language commands to Aider, get back created/edited files and full responses. Each client gets isolated workspaces. Works with any MCP-compatible client (Claude Desktop, custom apps, etc.).\n\n\n## Overview\n\nA production-ready MCP (Model Context Protocol) wrapper that exposes Aider's functionality over WebSocket, enabling editor plugins and services to interact with Aider programmatically. This project provides **two server implementations**:\n\n1. **`src/mcp-server.ts`** - **Real MCP Protocol Server** (Recommended)\n   - Implements standard JSON-RPC 2.0 MCP protocol  \n   - Proper MCP methods: `initialize`, `tools/list`, `tools/call`\n   - Smart completion detection (waits for Aider to finish)\n   - Compatible with Claude Desktop and other MCP clients\n\n2. **`src/index.ts`** - Custom WebSocket Wrapper\n   - Custom protocol with hello/welcome handshake\n   - Direct stdio pipe to Aider process\n   - Token-based authentication\n\n## Architecture\n\n```\n┌─────────────────┐         JSON-RPC 2.0        ┌─────────────────┐\n│   MCP Client    │ ◄─────────────────────────► │   MCP Server    │\n│  (Any MCP app)  │         WebSocket           │  (mcp-server.ts)│\n└─────────────────┘                             └────────┬────────┘\n                                                         │\n                                                         │ spawn()\n                                                         ▼\n                                                ┌─────────────────┐\n                                                │  Aider Process  │\n                                                │  (CLI instance) │\n                                                └─────────────────┘\n```\n\n## Features\n\n- **Full MCP Protocol Support**: Standard MCP methods and JSON-RPC 2.0\n- **Multi-tenant Isolation**: One Aider child process per client\n- **Automatic Completion Detection**: Waits for Aider to complete tasks\n- **Isolated Workspaces**: Each session gets its own workspace directory\n- **OpenAI API Integration**: Works with your existing OpenAI API key\n- **Real-time Communication**: WebSocket-based bidirectional communication\n- **Flexible Configuration**: Environment variables and CLI arguments\n- **Structured Logging**: JSON logging with Pino\n\n## Installation\n\n```bash\n# Clone and install\ngit clone \u003crepo-url\u003e\ncd aider_mcp\nnpm install\n\n# Configure environment\ncp .env.example .env\n# Edit .env and add your OpenAI API key:\n# OPENAI_API_KEY=sk-...\n```\n\n## Prerequisites\n\n- Node.js 18+\n- [Aider](https://aider.chat) installed and available in PATH\n- OpenAI API key\n\n## Usage\n\n### Running the Servers\n\n```bash\n# Run MCP protocol server (recommended)\nnpm run mcp\n\n# Run custom WebSocket wrapper\nnpm run dev\n\n# Production build\nnpm run build \u0026\u0026 npm start\n```\n\n### Testing\n\n```bash\n# Quick test of MCP server\npython3 test-debug.py\n\n# Full test with waiting\npython3 test-mcp-wait.py\n\n# JavaScript test client\nnode test-mcp-client.js\n```\n\n## MCP Protocol Communication\n\n### Available Tools\n\nThe MCP server exposes these tools to clients:\n\n1. **`aider_command`** - Execute natural language commands\n   ```json\n   {\n     \"name\": \"aider_command\",\n     \"arguments\": {\n       \"command\": \"create a REST API with Flask\"\n     }\n   }\n   ```\n\n2. **`aider_add_file`** - Add files to Aider's context\n   ```json\n   {\n     \"name\": \"aider_add_file\", \n     \"arguments\": {\n       \"filename\": \"app.py\"\n     }\n   }\n   ```\n\n3. **`aider_run_command`** - Run shell commands through Aider\n   ```json\n   {\n     \"name\": \"aider_run_command\",\n     \"arguments\": {\n       \"command\": \"npm test\"\n     }\n   }\n   ```\n\n### Connection Flow\n\n```javascript\n// 1. Connect via WebSocket\nconst ws = new WebSocket('ws://localhost:8080');\n\n// 2. Initialize MCP session\nws.send(JSON.stringify({\n  \"jsonrpc\": \"2.0\",\n  \"method\": \"initialize\",\n  \"params\": {\n    \"protocolVersion\": \"0.1.0\",\n    \"capabilities\": {},\n    \"clientInfo\": {\n      \"name\": \"your-client\",\n      \"version\": \"1.0.0\"\n    }\n  },\n  \"id\": 1\n}));\n\n// 3. Call tools after initialization\nws.send(JSON.stringify({\n  \"jsonrpc\": \"2.0\", \n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"aider_command\",\n    \"arguments\": {\n      \"command\": \"create a Python hello world script\"\n    }\n  },\n  \"id\": 2\n}));\n```\n\n## Configuration\n\n### Environment Variables\n\n```env\n# Required\nOPENAI_API_KEY=sk-...        # Your OpenAI API key\n\n# Optional\nPORT=8080                    # WebSocket server port (MCP server default)\nPORT=7011                    # WebSocket server port (custom wrapper default)\nAIDER_MODEL=gpt-4o-mini     # Default model\nWORKSPACES_DIR=./workspaces # Where to create project directories\nLOG_LEVEL=info              # Logging verbosity (debug|info|warn|error)\nVALID_TOKENS=token1,token2  # Auth tokens for custom wrapper (empty = no auth)\n```\n\n### CLI Arguments\n\nOverride configuration at runtime:\n\n```bash\n# Custom port and workspace\nnpm run mcp -- --port 9000\nnpm run dev -- --port 8080 --workspaces ./custom-workspaces\n\n# Override environment variables (custom wrapper only)\nnpm run dev -- --set AIDER_MODEL=gpt-4 --set LOG_LEVEL=debug\n```\n\n## Integration Examples\n\n### Claude Desktop App\n\nAdd to Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"aider\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/aider_mcp/dist/mcp-server.js\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"your-key\",\n        \"AIDER_MODEL\": \"gpt-4o-mini\"\n      }\n    }\n  }\n}\n```\n\n### Custom MCP Client\n\n```javascript\nimport { WebSocket } from 'ws';\n\nclass AiderMCPClient {\n  constructor(url = 'ws://localhost:8080') {\n    this.ws = new WebSocket(url);\n    this.requestId = 1;\n    this.setup();\n  }\n\n  async callTool(toolName, args) {\n    return this.sendRequest('tools/call', {\n      name: toolName,\n      arguments: args\n    });\n  }\n\n  sendRequest(method, params) {\n    const id = this.requestId++;\n    this.ws.send(JSON.stringify({\n      jsonrpc: '2.0',\n      method,\n      params,\n      id\n    }));\n  }\n}\n```\n\n## Project Structure\n\n```\naider_mcp/\n├── src/\n│   ├── index.ts              # Custom WebSocket wrapper\n│   └── mcp-server.ts         # Real MCP protocol server\n├── workspaces/               # Auto-generated client workspaces  \n├── test-*.py/js              # Various test clients\n├── package.json              # Node.js dependencies\n├── tsconfig.json             # TypeScript configuration\n├── .env                      # Environment configuration\n└── README.md                 # This file\n```\n\n## Scripts\n\n- `npm run mcp` - Start MCP protocol server (recommended)\n- `npm run dev` - Start custom WebSocket wrapper with hot reload\n- `npm run build` - Compile TypeScript to JavaScript\n- `npm start` - Start production server\n- `npm run lint` - Run ESLint\n- `npm run typecheck` - Run TypeScript type checking\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"ConnectionRefusedError\" or \"Connect call failed\"**\n   - Server isn't running. Start it with `npm run mcp`\n   - Wrong port. Check `.env` file (MCP default: 8080, Custom default: 7011)\n\n2. **\"Aider not found\"**\n   ```bash\n   # Install Aider\n   pip install aider-chat\n   \n   # Verify installation\n   which aider\n   ```\n\n3. **\"No API key\" or Aider errors**\n   - Add your OpenAI API key to `.env`:\n   ```\n   OPENAI_API_KEY=sk-proj-...\n   ```\n\n4. **Server returns too quickly / incomplete responses**\n   - Fixed in MCP server - waits for Aider to complete (3-second silence detection)\n\n5. **\"Tool execution timeout\"**\n   - Normal for complex tasks\n   - The MCP server waits as long as needed\n\n### Debug Mode\n\n```bash\n# Run with debug logging\nLOG_LEVEL=debug npm run mcp\n```\n\n### Checking Results\n\nFiles created by Aider are stored in workspace directories:\n\n```bash\n# List all workspaces\nls -la workspaces/\n\n# Check latest workspace  \nls -la workspaces/mcp-*/\n\n# View created files\ncat workspaces/mcp-*/your-file.py\n```\n\n## Security Considerations\n\n- **Isolated Workspaces**: Each client session gets its own directory\n- **Authentication**: Custom wrapper supports token-based auth via `VALID_TOKENS`\n- **Git Disabled**: Runs with `--no-git` by default for safety\n- **API Key Security**: Never commit `.env` file\n- **Production**: Consider running in Docker for additional isolation\n\n## Performance Notes\n\n- First request to Aider may take longer (model loading)\n- Subsequent requests are faster\n- The server maintains one Aider process per session\n- Workspace cleanup is manual (delete old directories as needed)\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarock22%2Faider-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flarock22%2Faider-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flarock22%2Faider-mcp/lists"}