TheBrain MCP Server

Interact with TheBrain's knowledge management system using its API.

An MCP (Model Context Protocol) server that enables AI assistants to interact with TheBrain's knowledge management system. This server provides comprehensive access to TheBrain's API, focusing on natural language interaction with TheBrain's powerful knowledge management capabilities.

MCP (Model Context Protocol)is a standard that lets AI assistants like Claude connect to external tools and services. Think of it as a translator between natural language and software APIs.

You → Claude → MCP Server → TheBrain API → Your Brain

- You say: "Create a project with three phases"
- Claude understandswhat you want to accomplish
- MCP Server translatesthis into specific TheBrain API calls
- TheBrain APIcreates the thoughts and connections
- Your Brainupdates with the new structure

The magic is thatyou don't need to know any technical details- just describe what you want in plain English!

- Content Management: Create, update, delete thoughts and notes
- File Attachments: Upload images, PDFs, documents to thoughts
- Web References: URL attachments with auto-title extraction
- Rich Notes: Full Markdown support with embedded content
- Relationship Mapping: Connect thoughts with meaningful relationships
- Search: Full-text search across thoughts, notes, and attachments
- Brain Management: Switch between multiple brains seamlessly
- Natural Language Interface: Describe what you want, Claude handles the details

The biggest limitation: Visual properties don't actually apply despite API success responses.

- ❌ Thought colors: API accepts colors but they don't appear in TheBrain
- ❌ Link colors: Similar issue - accepted but not applied
- ❌ Link thickness: API reports success but thickness doesn't change
- ❌ Visual formatting: All visual styling features are currently non-functional

- Intermittent connection problems: "Field required" errors after successful operations
- Long notes limitations: Issues with very long markdown content (keep under 10k characters)
- File path sensitivity: Requires absolute file paths; relative paths can fail
- Connection timing: MCP initialization race condition causing sporadic failures
- Memory constraints: Large file attachments can cause timeouts
- Search limitations: Complex queries sometimes return incomplete results

- Single-user operations: No real-time collaboration features
- No bulk operations: Can't import/export large datasets efficiently
- API connectivity required: No offline mode available
- TheBrain API limitations: Bound by existing API capabilities
- Authentication required: Must have valid TheBrain API key

Until visual styling is fixed, use these alternatives:

- Emojis for distinction: 🟢🟡🔴⚪🔵 instead of colors
- Descriptive names: "🔴 Urgent Task" instead of colored thoughts
- Rich markdown notes: Use formatting within notes for visual organization
- Hierarchical structure: Rely on parent/child relationships for organization

git clone https://github.com/redmorestudio/thebrain-mcp.git cd thebrain-mcp

THEBRAIN_API_KEY=your_api_key_here THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id

Add to your Claude Desktop configuration:

{ "mcpServers": { "thebrain": { "command": "node", "args": ["/absolute/path/to/thebrain-mcp/index.js"], "env": { "THEBRAIN_API_KEY": "your_api_key_here" } } } }

⚠️ Important: Use absolute file paths in the configuration and for file attachments.

- Restart Claude Desktop
- Verify.envfile has correct API key
- Always set active brain first: "Set my active brain to [name]"

- Use absolute file paths:/Users/username/Documents/file.pdf
- Check file permissions and existence
- Keep file sizes reasonable (< 50MB)

- Keep notes under 10,000 characters
- Break large content into multiple thoughts
- Use attachments for lengthy documents

- list_brains- List all available brains
- get_brain- Get brain details
- set_active_brain- Set the active brain for operations
- get_brain_stats- Get comprehensive brain statistics

- create_thought- Create thoughts (visual properties don't work)
- get_thought- Retrieve thought details
- update_thought- Update thought properties
- delete_thought- Delete a thought
- search_thoughts- Search across the brain
- get_thought_graph- Get thought with all connections
- get_types- List all thought types
- get_tags- List all tags

- create_link- Create links between thoughts (styling doesn't work)
- update_link- Modify link properties
- get_link- Get link details
- delete_link- Remove a link

- add_file_attachment- Attach files/images to thoughts ✅
- add_url_attachment- Attach web URLs ✅
- get_attachment- Get attachment metadata
- get_attachment_content- Download attachment content
- delete_attachment- Remove attachments
- list_attachments- List thought attachments

- get_note- Retrieve notes in markdown/html/text ✅
- create_or_update_note- Create or update notes ✅
- append_to_note- Append content to existing notes ✅

- get_modifications- View brain modification history

You: "Create a project called 'Kitchen Renovation'" Claude: Creates central project thought You: "Add phases for planning, demolition, and installation" Claude: Creates connected sub-thoughts for each phase You: "Attach my contractor quotes to the planning phase" Claude: Uploads files to the planning thought You: "Add a detailed note about the timeline to the project" Claude: Creates rich markdown note with your timeline

You: "Create a research topic about sustainable energy" Claude: Sets up main research thought You: "Add sub-topics for solar, wind, and hydro power" Claude: Creates organized thought hierarchy You: "Attach relevant papers and web articles" Claude: Adds file and URL attachments You: "Search for everything related to efficiency" Claude: Finds all relevant thoughts and content

- 🚨 Fix visual styling: Investigate why colors/thickness don't apply
- 🔧 Connection stability: Resolve MCP timing/race condition issues
- 📝 Long notes support: Better handling of extensive markdown content
- 🛡️ Error handling: More graceful failures and recovery

- Bulk operationsfor large-scale organization
- Enhanced templatesfor common workflows
- Performance optimizationsfor complex brains
- Offline capabilitiesand caching

- Natural language interface: No technical knowledge required
- Complete API coverage: 25+ tools spanning all TheBrain operations
- Robust error handling: Graceful failures and clear error messages
- Modular design: Clean, maintainable code architecture
- Production ready: Proper logging, testing, and documentation

- Version: 1.1.0 (June 2025)
- Core functionality: ✅ Complete and working
- Visual properties: ❌ Major issues need investigation
- Stability: 🟡 Generally stable with intermittent connection issues

Contributions are welcome! Areas where help is especially needed:

- Visual styling investigation: Why don't colors/thickness apply?
- Connection stability: Debugging MCP race conditions
- Performance optimization: Large brain handling
- Documentation: More usage examples and tutorials

Please feel free to submit issues or pull requests.

MIT License - seeLICENSEfile for details.

- TheBrain API Documentation:https://api.bra.in
- Issues & Bug Reports:https://github.com/redmorestudio/thebrain-mcp/issues
- Questions: Open a GitHub discussion

Connects to Anki via AnkiConnect to retrieve leech-tagged flashcards for use in Claude Desktop.