TheBrain MCP Server

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.

🔧 What's an MCP Server?

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.

How It Works:

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

1. You say: "Create a project with three phases"
2. Claude understands what you want to accomplish
3. MCP Server translates this into specific TheBrain API calls
4. TheBrain API creates the thoughts and connections
5. Your Brain updates with the new structure

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

🚀 What Actually Works

✅ Core Functionality (Working)

• 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

❌ Current Issues & Limitations

🚨 Major Visual Styling Problems

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

🐛 Other Known Issues

• 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

📋 API Dependencies & Constraints

• 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

🛠 Current Workarounds

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

Installation

1. Clone this repository:

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

2. Install dependencies:

npm install

3. Create a .env file with your API key:

THEBRAIN_API_KEY=your_api_key_here
THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id

Configuration

For Claude Desktop

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.

Debugging & Troubleshooting

Common Issues & Solutions

"Field required" errors:

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

File upload failures:

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

Long note problems:

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

Debug mode:

VERBOSE=true node index.js

Available Tools (25+ Functions)

Brain Management

• 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

Thought Operations

• 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

Link Operations

• 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

Attachment Operations

• 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

Note Operations

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

Advanced Features

• get_modifications - View brain modification history

Usage Examples (What Actually Works)

Project Organization

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

Research & Knowledge Management

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

🔮 Roadmap & Future Development

Immediate Priorities (v1.2.0)

• 🚨 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

Future Enhancements

• Bulk operations for large-scale organization
• Enhanced templates for common workflows
• Performance optimizations for complex brains
• Offline capabilities and caching

Technical Architecture

What Makes This Server Special

• 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

Current Status

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

Contributing

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.

License

MIT License - see LICENSE file for details.

Support

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

---

⚠️ Current Recommendation: Use this server for content management and organization with natural language interaction. Don't rely on visual styling features until they're fixed. The core functionality is solid and very useful for managing TheBrain content through conversation!