Brainrot

Brainrot MCP is a Model Context Protocol server that preserves your project decisions, TODOs, and architectural patterns so you can access them across any MCP-compatible AI assistant. It helps you prevent context loss between coding sessions and makes it easy to reuse learned patterns and priorities.

How to use

You interact with Brainrot MCP through an MCP client to push, retrieve, and organize context. Use push_context to store decisions and TODOs with tags and priorities. Retrieve saved context with pop_context to get smart guidance and instructions based on past decisions. List or filter contexts with list_contexts to quickly find relevant items across sessions. All data persists locally (or in the configured backend) and is designed to flow across multiple MCP-enabled assistants and sessions.

How to install

# Prerequisites
- Python 3.11+
- uv (or Python environment management)
- A client that supports MCP (e.g., Claude Desktop)

# 1) Clone the project
git clone https://example.invalid/brainrot-mcp.git
cd brainrot-mcp

# 2) Set up a Python virtual environment (example commands)
uv venv
uv pip install -r backend/requirements.txt
uv pip install -r mcp_server/requirements.txt

# 3) Start the backend API server (http endpoint)
python backend/server.py

# Optional: enable vector search (if supported by your setup)
ENABLE_VECTOR_SEARCH=true uv run python server.py

# The API server will be available at http://localhost:8000

Configuration and usage notes

Configure your MCP client to point to Brainrot MCP so you can access stored contexts from your preferred environment. An example client setup is shown for Claude Desktop where the backend URL is provided to the client so it can reach the MCP server.

Troubleshooting

If Brainrot MCP is not connecting, ensure the backend is running on port 8000 and that your client uses the correct backend URL. Restart your MCP client after any config changes. If you encounter database issues, verify that the SQLite database file is accessible at data/brainrot.db and check file permissions.

Real-world usage patterns

Store an architecture decision, then retrieve it later with smart guidance. For example, push a key decision about authentication strategy with relevant tags and a priority. Later, pop_context can return a concise, actionable summary and usage guidance based on that decision.

Notes on deployment and environment

Brainrot MCP runs a local HTTP API and can be run as a local stdio process for tighter integration with MCP clients. The HTTP API is the primary surface for remote clients, while the stdio mode enables direct command piping from your development environment.

Available tools

push_context

Store context with auto-summarization so you can retrieve it later with guidance and tags

pop_context

Retrieve stored context with smart instructions and usage guidance tailored to your tags and priorities

list_contexts

Filter and list stored contexts by tags, priorities, or other attributes to manage memory efficiently

delete_context

Remove outdated or irrelevant contexts to keep memory clean