TheBrain MCP Server

1# TheBrain MCP Server
2 
3An 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.
4 
5## 🔧 What's an MCP Server?
6 
7**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.
8 
9### How It Works:
10```
11You → Claude → MCP Server → TheBrain API → Your Brain
12```
13 
141. **You say**: "Create a project with three phases"
152. **Claude understands** what you want to accomplish  
163. **MCP Server translates** this into specific TheBrain API calls
174. **TheBrain API** creates the thoughts and connections
185. **Your Brain** updates with the new structure
19 
20The magic is that **you don't need to know any technical details** - just describe what you want in plain English!
21 
22## 🚀 What Actually Works
23 
24### ✅ **Core Functionality (Working)**
25- **Content Management**: Create, update, delete thoughts and notes
26- **File Attachments**: Upload images, PDFs, documents to thoughts
27- **Web References**: URL attachments with auto-title extraction  
28- **Rich Notes**: Full Markdown support with embedded content
29- **Relationship Mapping**: Connect thoughts with meaningful relationships
30- **Search**: Full-text search across thoughts, notes, and attachments
31- **Brain Management**: Switch between multiple brains seamlessly
32- **Natural Language Interface**: Describe what you want, Claude handles the details
33 
34## ❌ Current Issues & Limitations
35 
36### 🚨 **Major Visual Styling Problems**
37**The biggest limitation**: Visual properties don't actually apply despite API success responses.
38 
39- **❌ Thought colors**: API accepts colors but they don't appear in TheBrain
40- **❌ Link colors**: Similar issue - accepted but not applied  
41- **❌ Link thickness**: API reports success but thickness doesn't change
42- **❌ Visual formatting**: All visual styling features are currently non-functional
43 
44### 🐛 **Other Known Issues**
45- **Intermittent connection problems**: "Field required" errors after successful operations
46- **Long notes limitations**: Issues with very long markdown content (keep under 10k characters)
47- **File path sensitivity**: Requires absolute file paths; relative paths can fail
48- **Connection timing**: MCP initialization race condition causing sporadic failures
49- **Memory constraints**: Large file attachments can cause timeouts
50- **Search limitations**: Complex queries sometimes return incomplete results
51 
52### 📋 **API Dependencies & Constraints**
53- **Single-user operations**: No real-time collaboration features
54- **No bulk operations**: Can't import/export large datasets efficiently  
55- **API connectivity required**: No offline mode available
56- **TheBrain API limitations**: Bound by existing API capabilities
57- **Authentication required**: Must have valid TheBrain API key
58 
59## 🛠 **Current Workarounds**
60 
61Until visual styling is fixed, use these alternatives:
62- **Emojis for distinction**: 🟢🟡🔴⚪🔵 instead of colors
63- **Descriptive names**: "🔴 Urgent Task" instead of colored thoughts
64- **Rich markdown notes**: Use formatting within notes for visual organization
65- **Hierarchical structure**: Rely on parent/child relationships for organization
66 
67## Installation
68 
691. Clone this repository:
70```bash
71git clone https://github.com/redmorestudio/thebrain-mcp.git
72cd thebrain-mcp
73```
74 
752. Install dependencies:
76```bash
77npm install
78```
79 
803. Create a `.env` file with your API key:
81```bash
82THEBRAIN_API_KEY=your_api_key_here
83THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id
84```
85 
86## Configuration
87 
88### For Claude Desktop
89 
90Add to your Claude Desktop configuration:
91 
92```json
93{
94  "mcpServers": {
95    "thebrain": {
96      "command": "node",
97      "args": ["/absolute/path/to/thebrain-mcp/index.js"],
98      "env": {
99        "THEBRAIN_API_KEY": "your_api_key_here"
100      }
101    }
102  }
103}
104```
105 
106**⚠️ Important**: Use absolute file paths in the configuration and for file attachments.
107 
108## Debugging & Troubleshooting
109 
110### Common Issues & Solutions
111 
112**"Field required" errors**:
113- Restart Claude Desktop
114- Verify `.env` file has correct API key
115- Always set active brain first: "Set my active brain to [name]"
116 
117**File upload failures**:
118- Use absolute file paths: `/Users/username/Documents/file.pdf`
119- Check file permissions and existence
120- Keep file sizes reasonable (< 50MB)
121 
122**Long note problems**:
123- Keep notes under 10,000 characters
124- Break large content into multiple thoughts
125- Use attachments for lengthy documents
126 
127**Debug mode**:
128```bash
129VERBOSE=true node index.js
130```
131 
132## Available Tools (25+ Functions)
133 
134### Brain Management
135- `list_brains` - List all available brains
136- `get_brain` - Get brain details
137- `set_active_brain` - Set the active brain for operations
138- `get_brain_stats` - Get comprehensive brain statistics
139 
140### Thought Operations
141- `create_thought` - Create thoughts (visual properties don't work)
142- `get_thought` - Retrieve thought details
143- `update_thought` - Update thought properties
144- `delete_thought` - Delete a thought
145- `search_thoughts` - Search across the brain
146- `get_thought_graph` - Get thought with all connections
147- `get_types` - List all thought types
148- `get_tags` - List all tags
149 
150### Link Operations
151- `create_link` - Create links between thoughts (styling doesn't work)
152- `update_link` - Modify link properties
153- `get_link` - Get link details
154- `delete_link` - Remove a link
155 
156### Attachment Operations
157- `add_file_attachment` - Attach files/images to thoughts ✅
158- `add_url_attachment` - Attach web URLs ✅
159- `get_attachment` - Get attachment metadata
160- `get_attachment_content` - Download attachment content
161- `delete_attachment` - Remove attachments
162- `list_attachments` - List thought attachments
163 
164### Note Operations
165- `get_note` - Retrieve notes in markdown/html/text ✅
166- `create_or_update_note` - Create or update notes ✅
167- `append_to_note` - Append content to existing notes ✅
168 
169### Advanced Features
170- `get_modifications` - View brain modification history
171 
172## Usage Examples (What Actually Works)
173 
174### Project Organization
175```
176You: "Create a project called 'Kitchen Renovation'"
177Claude: Creates central project thought
178 
179You: "Add phases for planning, demolition, and installation"  
180Claude: Creates connected sub-thoughts for each phase
181 
182You: "Attach my contractor quotes to the planning phase"
183Claude: Uploads files to the planning thought
184 
185You: "Add a detailed note about the timeline to the project"
186Claude: Creates rich markdown note with your timeline
187```
188 
189### Research & Knowledge Management
190```
191You: "Create a research topic about sustainable energy"
192Claude: Sets up main research thought
193 
194You: "Add sub-topics for solar, wind, and hydro power"
195Claude: Creates organized thought hierarchy
196 
197You: "Attach relevant papers and web articles"
198Claude: Adds file and URL attachments
199 
200You: "Search for everything related to efficiency"
201Claude: Finds all relevant thoughts and content
202```
203 
204## 🔮 Roadmap & Future Development
205 
206### **Immediate Priorities (v1.2.0)**
207- **🚨 Fix visual styling**: Investigate why colors/thickness don't apply
208- **🔧 Connection stability**: Resolve MCP timing/race condition issues  
209- **📝 Long notes support**: Better handling of extensive markdown content
210- **🛡️ Error handling**: More graceful failures and recovery
211 
212### **Future Enhancements**
213- **Bulk operations** for large-scale organization
214- **Enhanced templates** for common workflows
215- **Performance optimizations** for complex brains  
216- **Offline capabilities** and caching
217 
218## Technical Architecture
219 
220### What Makes This Server Special
221- **Natural language interface**: No technical knowledge required
222- **Complete API coverage**: 25+ tools spanning all TheBrain operations
223- **Robust error handling**: Graceful failures and clear error messages
224- **Modular design**: Clean, maintainable code architecture
225- **Production ready**: Proper logging, testing, and documentation
226 
227### Current Status
228- **Version**: 1.1.0 (June 2025)
229- **Core functionality**: ✅ Complete and working
230- **Visual properties**: ❌ Major issues need investigation
231- **Stability**: 🟡 Generally stable with intermittent connection issues
232 
233## Contributing
234 
235Contributions are welcome! Areas where help is especially needed:
236 
237- **Visual styling investigation**: Why don't colors/thickness apply?
238- **Connection stability**: Debugging MCP race conditions
239- **Performance optimization**: Large brain handling
240- **Documentation**: More usage examples and tutorials
241 
242Please feel free to submit issues or pull requests.
243 
244## License
245 
246MIT License - see [LICENSE](LICENSE) file for details.
247 
248## Support
249 
250- **TheBrain API Documentation**: https://api.bra.in
251- **Issues & Bug Reports**: https://github.com/redmorestudio/thebrain-mcp/issues
252- **Questions**: Open a GitHub discussion
253 
254---
255 
256**⚠️ 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!
257