cursor-buddy

Cursor Buddy MCP turns your project into a context-aware coding partner. It exposes a set of built-in tools that help you manage project context, search knowledge, track todos, and inspect the database schema and history. The server runs inside a container and communicates with MCP clients over JSON-RPC 2.0 via standard input/output, enabling integration with agents like Claude Desktop. To use it, mount your project’s .buddy directory into the container so the MCP server can read and update your project context in real time. The included tools include: buddy_get_rules to retrieve coding standards, buddy_search_knowledge to perform full-text searches across project docs, buddy_manage_todos to view and update tasks, buddy_get_database_info for schema and query validation, buddy_history to examine implementation history, and buddy_backup to create and manage safe backups. You can combine these tools with natural-language prompts to keep your AI aligned with your project’s conventions and to track progress as you work.

Prerequisites:

• Docker installed and running on your machine.
• An existing project with a .buddy folder (or plan to create one within your project).

Step-by-step:

1. Pull the latest Cursor Buddy MCP image (already provided by the README example): docker pull ghcr.io/omar-haris/cursor-buddy-mcp:latest

2. Configure the MCP server to point at your project context:

   • Create or update your .cursor/mcp.json (or equivalent) with the following content, adjusting the path to your project’s .buddy folder:

   { "mcpServers": { "cursor-buddy-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/path/to/your/project/.buddy:/home/buddy/.buddy", "-e", "BUDDY_PATH=/home/buddy/.buddy", "ghcr.io/omar-haris/cursor-buddy-mcp:latest" ] } } }

3. Start the MCP server using the configuration above. If you’re using the docker approach, ensure the mounted path points to your actual project’s .buddy folder.

4. Connect an MCP client (e.g., Claude Desktop) using JSON-RPC over STDIN/STDOUT as described by MCP, and point it to the configured server alias (cursor-buddy-mcp).

Tips and common considerations:

• Ensure the -v mount path (/path/to/your/project/.buddy) exists and contains your rules, knowledge, todos, database, history, and backups directories.
• The BUDDY_PATH environment variable should point to the mounted .buddy directory inside the container for the server to locate context data.
• The server communicates via JSON-RPC 2.0 over STDIO; use an MCP client that supports this protocol.
• If you update contents under .buddy, the Real-time Updates feature will keep the AI in sync; verify file watching is enabled in the container if you don’t see immediate changes.
• When upgrading the image, re-run the container with the updated image tag to pick up new capabilities.
• For Windows users, ensure the path mappings use proper drive-letter syntax, e.g., C:/path/to/project/.buddy:/home/buddy/.buddy.