TheBrain MCP Server
Supports creating, updating, and retrieving rich notes with full Markdown formatting, including embedded content and organizational styling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TheBrain MCP Server Create a new thought called 'Meeting Notes' under 'Project Alpha'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 BrainYou say: "Create a project with three phases"
Claude understands what you want to accomplish
MCP Server translates this into specific TheBrain API calls
TheBrain API creates the thoughts and connections
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
Clone this repository:
git clone https://github.com/redmorestudio/thebrain-mcp.git
cd thebrain-mcpInstall dependencies:
npm installCreate a
.envfile with your API key:
THEBRAIN_API_KEY=your_api_key_here
THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_idConfiguration
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
.envfile has correct API keyAlways set active brain first: "Set my active brain to [name]"
File upload failures:
Use absolute file paths:
/Users/username/Documents/file.pdfCheck 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.jsAvailable Tools (25+ Functions)
Brain Management
list_brains- List all available brainsget_brain- Get brain detailsset_active_brain- Set the active brain for operationsget_brain_stats- Get comprehensive brain statistics
Thought Operations
create_thought- Create thoughts (visual properties don't work)get_thought- Retrieve thought detailsupdate_thought- Update thought propertiesdelete_thought- Delete a thoughtsearch_thoughts- Search across the brainget_thought_graph- Get thought with all connectionsget_types- List all thought typesget_tags- List all tags
Link Operations
create_link- Create links between thoughts (styling doesn't work)update_link- Modify link propertiesget_link- Get link detailsdelete_link- Remove a link
Attachment Operations
add_file_attachment- Attach files/images to thoughts ✅add_url_attachment- Attach web URLs ✅get_attachment- Get attachment metadataget_attachment_content- Download attachment contentdelete_attachment- Remove attachmentslist_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 timelineResearch & 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!
Available Tools
26 toolsadd_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_linkB
Create a link between two thoughts with visual properties
Inputs: relation (required), thoughtIdA (required), thoughtIdB (required), name, +5 more.
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_linkC
Delete a link
Inputs: linkId (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_linkB
Get details about a specific link
Inputs: linkId (required), 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_linkC
Update link properties including visual formatting
Inputs: linkId (required), name, color, brainId, +3 more.
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Turn your notes, links and conversations into a Living Brain your AI tools share and build on.
Your personal knowledge base and memory for AI agents: search, explore and feed your myBrain.
Turn AI conversations into visual knowledge maps. Create, connect, search, and organize thoughts.
Mind maps with a full document in every node. Read, search and edit your maps from AI tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Brain service for thought management, including saving thoughts with metadata, quick capture with auto-classification, searching, and retrieving entries through natural language.-
- AlicenseNot gradedqualityAmaintenanceEnables 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.3Apache 2.0
- FlicenseNot gradedqualityDmaintenanceWraps TheBrain knowledge graph as an MCP server, enabling AI assistants to search, create, and manage thoughts, links, and notes via natural language.5-
- AlicenseAqualityDmaintenanceEnables 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.164 npm4MIT