project-thebrain

Project TheBrain MCP Server provides a Ruby-based MCP implementation that enables AI assistants and MCP clients to interact with TheBrain’s knowledge base via the Model Context Protocol. The server exposes tools for querying, retrieving, creating, updating, and deleting thoughts within TheBrain’s network, allowing AI models to perform semantic search, content analysis, and knowledge manipulation through standardized JSON-RPC 2.0 requests. Clients like Claude Desktop, VS Code MCP integrations, or other MCP clients can initialize a session, request tool lists, and invoke specific tool handlers such as search_thoughts, get_thought, create_thought, update_thought, and delete_thought, with the server orchestrating calls to TheBrain’s REST API and internal caching and error handling.

Prerequisites:

• Docker installed on your machine or deployment host
• Access credentials (API URL and API key) for TheBrain REST API
• (Optional) A TheBrain brain identifier if multiple brains are used

1. Prepare environment variables

• Create a .env file or set environment variables in your deployment environment: THEBRAIN_API_URL=https://your-thebrain-api.example.com THEBRAIN_API_KEY=your_thebrain_api_key BRAINS_ID=your_brain_id

2. Run the MCP server

• If using Docker (recommended for isolation): docker run -i
  -e THEBRAIN_API_URL=$THEBRAIN_API_URL
  -e THEBRAIN_API_KEY=$THEBRAIN_API_KEY
  -e BRAINS_ID=$BRAINS_ID
  ghcr.io/enogrob/project-thebrain-mcp-server:latest

3. Verify the server is running

• Check container logs for initialization messages and readiness indicators.
• Ensure the server can reach TheBrain API endpoints (network access and firewall rules may apply).

4. Optional: CLI or client setup

• Point your MCP client to the running server endpoint (e.g., via standard MCP transport, such as stdio if using a local runner, or HTTP/RPC if exposed).

Notes and tips:

• Ensure the THEBRAIN_API_URL and THEBRAIN_API_KEY have the necessary permissions to read and modify thoughts in the target brain.
• If using multiple brains, verify BRAINS_ID or corresponding configuration in the server to avoid cross-brain operations.
• The server leverages a memory cache (concurrent-ruby) to speed up frequent reads; monitor cache TTL and eviction behavior as needed.
• If you encounter authentication or rate-limit errors from TheBrain, check token scopes and API usage limits in your TheBrain account.
• For production deployments, consider mounting a persistent volume for logs and configuring a structured logger (dry-logger) to integrate with your observability stack.