Skip to main content
Glama

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!

Related MCP server: TheBrain MCP Server

🚀 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
  1. Install dependencies:

npm install
  1. 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

  • 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


⚠️ 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!

Available Tools

26 tools
add_file_attachmentB

Add a file attachment (including images) to a thought

Inputs: filePath (required), thoughtId (required), brainId, fileName.

add_url_attachmentB

Add a URL attachment to a thought

Inputs: url (required), thoughtId (required), name, brainId.

append_to_noteC

Append content to an existing note

Inputs: markdown (required), thoughtId (required), brainId.

create_or_update_noteC

Create or update a note with markdown content

Inputs: markdown (required), thoughtId (required), brainId.

create_thoughtC

Create a new thought with optional visual properties

Inputs: name (required), kind, label, acType, +6 more.

delete_attachmentC

Delete an attachment

Inputs: attachmentId (required), brainId.

delete_thoughtC

Delete a thought

Inputs: thoughtId (required), brainId.

get_attachmentC

Get metadata about an attachment

Inputs: attachmentId (required), brainId.

get_attachment_contentC

Get the binary content of an attachment (e.g., download an image)

Inputs: attachmentId (required), brainId, saveToPath.

get_brainC

Get details about a specific brain

Inputs: brainId (required).

get_brain_statsC

Get statistics about a brain

Inputs: brainId.

get_modificationsB

Get modification history for a brain

Inputs: brainId, endTime, maxLogs, startTime.

get_noteB

Get the note content for a thought

Inputs: thoughtId (required), format, brainId.

get_tagsC

Get all tags in a brain

Inputs: brainId.

get_thoughtC

Get details about a specific thought

Inputs: thoughtId (required), brainId.

get_thought_graphC

Get a thought with all its connections and attachments

Inputs: thoughtId (required), brainId, includeSiblings.

get_typesC

Get all thought types in a brain

Inputs: brainId.

list_attachmentsC

List all attachments for a thought

Inputs: thoughtId (required), brainId.

list_brainsA

List all available brains for the user

Inputs: no named parameters.

search_thoughtsC

Search for thoughts in a brain

Inputs: queryText (required), brainId, maxResults, onlySearchThoughtNames.

set_active_brainC

Set the active brain for subsequent operations

Inputs: brainId (required).

update_thoughtB

Update a thought including its visual properties

Inputs: thoughtId (required), kind, name, label, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 26 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. For example, get_thought retrieves basic thought data while get_thought_graph includes connections and attachments. Even similar actions like append_to_note and create_or_update_note are well-differentiated by their descriptions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with underscores (e.g., create_thought, get_attachment, delete_link). The verbs are uniform and descriptive, making the pattern predictable and easy to follow.

    Tool Count4/5

    At 26 tools, the set is on the high side but still justified given the complexity of TheBrain's features (thoughts, notes, links, attachments, brains, tags, etc.). Each tool serves a specific operation, and there is minimal redundancy.

    Completeness5/5

    The tool surface covers the full lifecycle of thoughts, notes, links, attachments, and brain management. Operations include create, read, update, delete, search, and listing. No obvious gaps are apparent for the stated domain.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Brain service for thought management, including saving thoughts with metadata, quick capture with auto-classification, searching, and retrieving entries through natural language.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to interact with TheBrain's knowledge management system through natural language for managing thoughts, notes, and attachments. It supports core features like full-text search, relationship mapping, and file uploads to streamline digital brain organization.
      3
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.
      16
      4 npm
      4
      MIT