thebrain

TheBrain MCP & API Server exposes TheBrain knowledge graph via MCP (Model Context Protocol) alongside a RESTful API. It supports a comprehensive set of MCP tools for interacting with ideas (thoughts), links between thoughts, notes, and metadata, enabling AI assistants to search, retrieve, and manipulate the brain’s structure. Core capabilities include advanced search with enhanced fields, graph retrieval (get_graph), full context extraction (get_context), multi-layer neighbor exploration (explore_neighbors), and batch note updates. Authentication for REST endpoints is done with a Bearer token using your THEBRAIN_API_KEY. The MCP tools mirror the REST operations, allowing you to search thoughts, fetch thought details, create or update thoughts and links, manage notes, and list metadata, all through a consistent interface.

Typical usage flows involve using get_graph to understand a thought’s network, get_context for a complete snapshot of an idea (including notes and related nodes), and explore_neighbors to traverse deeper relationships. For batch text edits, batch_replace_note enables large-scale note updates. The combination of REST endpoints and MCP tools supports seamless integration with AI assistants and automation workflows, enabling tasks such as knowledge discovery, graph visualization, and structured data updates within TheBrain.

Prerequisites:

• Docker and Docker-Compose (recommended) or a Python/Node environment if you choose alternative deployment methods
• Access keys or environment-specific credentials for TheBrain API (THEBRAIN_API_KEY, THEBRAIN_BRAIN_ID)

Installation steps (Docker-based):

1. Prepare environment variables

   • Copy and edit the example env file if provided, or export directly: export THEBRAIN_API_KEY=your_api_key_here export THEBRAIN_BRAIN_ID=your_brain_id_here

2. Pull and run the MCP server image (recommended)

   • Ensure you have a suitable docker image name for thebrain-mcp-server
   • Start the container: docker run -d --name thebrain-mcp-server -e THEBRAIN_API_KEY="$THEBRAIN_API_KEY" -e THEBRAIN_BRAIN_ID="$THEBRAIN_BRAIN_ID" thebrain-mcp-server

3. Verify the service

   • Access API docs and MCP endpoint: REST: http://localhost:8000/docs MCP: http://localhost:8000/mcp/mcp

Alternative (local development in Python/Node environments):

• Install dependencies (e.g., Python 3.10+ and pip or Node.js with npm)
• Set up a virtual environment and install required packages from requirements.txt or package.json
• Run the server script or entry point as documented in the repository (e.g., python api_server.py or node server.js)

Prerequisites recap:

• Docker or a local dev environment capable of running the server
• Access to TheBrain API key and brain ID
• Basic familiarity with environment variable configuration

Tips:

• Ensure THEBRAIN_API_KEY and THEBRAIN_BRAIN_ID are correctly set in the environment before starting the container.
• The MCP endpoint is at /mcp/mcp and the REST API at /docs (Swagger UI) for interactive exploration.
• If you encounter authentication errors, regenerate or verify your API key permissions in TheBrain admin console.
• For large graph operations, consider using get_graph with appropriate depth and then switch to get_context for a full snapshot when needed.
• When deploying with Docker, you may map ports as needed (e.g., -p 8000:8000) to expose the API securely in your environment.
• The REST API supports 22 endpoints for thoughts, links, notes, and statistics; refer to the docs for exact parameter names and response structures.