brain-mcp-server
JEM-Fizbit/brain-mcp-server
Generic MCP server for Markdown-based AI Brain context systems
Instalação
npx convez-ai JEM-Fizbit/brain-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
brain-mcp-server
A generic MCP server that serves Markdown-based AI Brain files to any MCP-compatible client.
What It Does
Gives MCP clients persistent, context-aware access to a collection of Markdown files (an "AI Brain") via the Model Context Protocol. Supports reading, writing, searching, git-backed versioning, local stdio transport, and hosted HTTP transport with GitHub OAuth.
Tools
| Tool | Description |
|---|---|
brain_load_context | Entry point — returns the loader + NOW.md, plus lint, issue, and inbox nudges |
brain_read_file | Read a specific file. Accepts scope = brain (default) or sources to read from the sources/ archive |
brain_update_file | Update a Brain file (replace, append, or patch) |
brain_commit | Git commit changes, optionally push |
brain_list_files | List all Brain files with staleness metadata |
brain_list_sources | List files in the sources/ archive, with optional category filter |
brain_search | Search for keywords. Accepts scope = brain (default), sources, or all |
brain_log | Append an entry to the Brain change log |
brain_read_log | Read recent change log entries |
brain_lint | Run a health check (bloat, staleness, orphan backlinks, drift, missing cross-references) |
brain_ingest | Process a new source — dry-run analysis or save to sources/ |
brain_ingest_complete | Record provenance after ingest (updates SOURCES.md + LOG.md, optionally deletes inbox file) |
brain_scan_inbox | List files pending in the inbox/ drop-folder for processing |
The scope parameter on brain_read_file and brain_search separates the Brain vault (curated summaries, default) from the sources/ archive (original ingested documents: bios, assessments, meeting notes, writing samples, analysis, correspondence, etc.). Claude escalates scope automatically when a query implicates original material rather than a Brain summary.
Requirements
- Node.js 18+
- A directory of Markdown files (your "Brain") with at least
00_loader.mdandNOW.md - Git initialised in the Brain directory (for commit/push features)
Quick Start
# 1. Clone and build
git clone <your-fork-or-clone-url> ~/Projects/brain-mcp-server
cd ~/Projects/brain-mcp-server
npm install
npm run build
# 2. Verify the build produced dist/index.js
ls dist/index.js
# 3. Test with MCP Inspector (optional but recommended)
npx @modelcontextprotocol/inspector node dist/index.js
Configuration
| Variable | Description | Default |
|---|---|---|
BRAIN_DIR | Absolute path to your Brain markdown files directory | ~/Projects/ai-brain-jem/brain |
BRAIN_SOURCES_DIR | Absolute path to your source archive directory | sibling sources/ next to BRAIN_DIR |
TRANSPORT | stdio by default, or http for hosted/HTTP mode | unset / stdio |
HOST or MCP_HTTP_HOST | HTTP bind host when TRANSPORT=http | 127.0.0.1 |
PORT | HTTP bind port and local OAuth base fallback | 3000 |
MCP_OAUTH_PUBLIC_BASE | Public HTTPS base URL for hosted OAuth and MCP metadata | http://127.0.0.1:$PORT |
MCP_OAUTH_SIGNING_SECRET | Required in HTTP mode. HS256 access-token signing secret | unset |
GITHUB_OAUTH_CLIENT_ID | Required in HTTP mode. GitHub OAuth app client ID | unset |
GITHUB_OAUTH_CLIENT_SECRET | Required in HTTP mode. GitHub OAuth app client secret | unset |
GITHUB_ALLOWED_LOGINS | Comma-separated GitHub login allowlist for fallback owner access | unset |
GITHUB_ALLOWED_EMAILS | Comma-separated email allowlist for fallback owner access | unset |
BRAIN_PLATFORM_CONFIG | Registry JSON path for hosted/multi-Brain mode | ~/.config/brain-platform/registry.json |
BRAIN_PLATFORM_STATE_ROOT | File-backed OAuth state root | ~/.config/brain-platform/state |
BRAIN_AUTO_SYNC | Filesystem/git mode only. When true, successful mutating Brain tools automatically commit changes. Do not enable for Supabase-backed hosted runtime | unset / false |
BRAIN_AUTO_PUSH | Filesystem/git mode only. When auto-sync is enabled, push commits to origin unless set false. Do not enable for Supabase-backed hosted runtime | true |
BRAIN_DATE_TIME_ZONE | IANA timezone used for Brain log/source dates | TZ or UTC |
Hosted HTTP Deployment
Remote-only clients need a public HTTPS MCP endpoint; 127.0.0.1 only works for clients running on the same laptop. The current hosted rebuild targets a Node runtime that serves OAuth and MCP over HTTPS while storing Brain revisions in Supabase Postgres and source artifacts in private Supabase Storage. The local Markdown Brain remains the baseline and is mirrored through the sync contract rather than by a hosted git checkout.
This repo includes:
Dockerfilefor the hosted Node runtimefly.tomlfor the first Supabase-backed Fly.io target,jem-brain-mcpdocs/deploy-fly.mdfor the deployment runbookdocs/ROADMAP.mdfor the staged JEM cutover, ERS migration, and multi-tenant roadmap
Hosted endpoint shape:
https://jem-brain-mcp.fly.dev/mcp
Client Setup
Claude Code
Add to ~/.claude/settings.json (user-level) or .claude/settings.json (project-level):
{
"mcpServers": {
"brain": {
"command": "node",
"args": ["/absolute/path/to/brain-mcp-server/dist/index.js"],
"env": {
"BRAIN_DIR": "/absolute/path/to/your/brain/files"
}
}
}
}
Claude Desktop
Add to claude_desktop_config.json (same format as above).
Claude Cowork
Add via the MCP server configuration in Cowork settings (same command, args, and env values).
Post-Install Configuration
After the MCP server is connected, three additional steps make it fully automatic.
Step 1: Pre-authorise tool calls (Claude Code)
Add mcp__brain to your permissions allow-list so Claude doesn't prompt for approval on every Brain tool call.
In ~/.claude/settings.json, add to the permissions.allow array:
{
"permissions": {
"allow": [
"mcp__brain"
]
}
}
This matches all thirteen Brain tools. You can verify with /permissions in Claude Code.
Step 2: Conditional auto-load directive (Claude Code / Cowork)
Add the following to ~/.claude/CLAUDE.md so Claude loads Brain context when relevant — not on every conversation:
## AI Brain (Conditional Auto-Load)
An AI Brain (personal knowledge system) is connected via MCP. Load it when the conversation
benefits from personal context — skip it for generic tasks.
Load Brain context proactively (don't wait to be asked) when:
- Writing on the user's behalf, career/professional tasks, work context, personal projects,
strategy/advice requiring background, anything needing voice/preferences/expertise,
user references "my Brain" / "my context", or user attaches a document or asks to ingest.
Skip when:
- Generic technical questions, general knowledge/research, pure coding help,
or user explicitly says not to load.
Load sequence (when loading):
1. Fetch tools (if deferred): ToolSearch(query="select:mcp__brain__brain_load_context,mcp__brain__brain_read_file,mcp__brain__brain_search,mcp__brain__brain_list_files,mcp__brain__brain_list_sources,mcp__brain__brain_update_file,mcp__brain__brain_commit,mcp__brain__brain_log,mcp__brain__brain_read_log,mcp__brain__brain_lint,mcp__brain__brain_ingest,mcp__brain__brain_ingest_complete,mcp__brain__brain_scan_inbox")
2. Call brain_load_context — returns the loader navigation table, current priorities, and nudges (lint overdue, inbox pending). The loader contains the full ingestion protocol, source categories, and file-editing rules; follow it.
3. Call brain_read_file for task-relevant files per the navigation table.
4. If brain_load_context flags a lint nudge, run brain_lint before accuracy-sensitive work.
Reading source archives:
- brain_read_file and brain_search accept scope = "brain" (default, vault only), "sources", or "all" (search only). Escalate scope automatically when a query implicates original ingested material rather than a Brain summary.
- Use brain_list_sources (optional category filter) to discover source files.
Inbox: files dropped into the inbox/ folder are pending sources. Use brain_scan_inbox when asked, then process each using the ingestion protocol in the loader. The inbox_file parameter on brain_ingest_complete handles cleanup.
This works for both Claude Code and Cowork (both read ~/.claude/CLAUDE.md).
Step 3: User preferences (Claude Desktop / claude.ai — manual)
Claude Desktop and claude.ai do not read CLAUDE.md. For these clients, add the conditional auto-load directive to your user preferences (Settings → Profile → User preferences).
See MANUAL_SETUP.md for the exact text to paste, verification tests, and a troubleshooting checklist.
Note: This step requires manual entry in each client's preferences UI. It cannot be automated.
How It Works
- Claude calls
brain_load_contextat session start (automatically, if configured per above) - The response includes the loader, NOW.md, and nudges (lint overdue, open maintenance issues, pending inbox files)
- Claude reads the navigation table and requests specific files via
brain_read_file - Edits are written via
brain_update_file, then committed viabrain_commit - New information is processed via
brain_ingest(dry-run analysis, then guided updates) - Changes are tracked via
brain_log; health is checked viabrain_lint
The routing logic lives in the loader (a Markdown file you maintain), not in code. The server is content-agnostic — it knows nothing about your specific Brain content, only how to serve Markdown files.
Brain files use [[backlinks]] (Obsidian-style wikilinks) to cross-reference each other. During ingest, the LLM maintains these links across all affected files. The lint process checks for orphan content files (zero inbound backlinks). The Brain directory can be opened as an Obsidian vault for graph view and backlink navigation.
Recommended Workflow
The MCP server works from any Claude client, but different tasks suit different clients:
| Activity | Best client | Why |
|---|---|---|
| Using Brain in conversation | Chat (any client with MCP) | All read/write tools work over stdio — no uploads needed |
| Small updates (NOW.md, tasks, journal) | Chat | brain_update_file + brain_commit handle it directly |
| Large document ingestion | Cowork or Code | Multi-step workflow needs filesystem access to sources/ |
| Drop-folder ingestion | Any (via scheduled task) | Drop files into inbox/, daily task processes them automatically |
| Server code maintenance | Code | Iterative build-test-commit cycle |
| Brain repo git operations | Code | Shell access for rebasing, conflict resolution, pushing |
| Graph view & knowledge mapping | Obsidian | Open brain/ as a vault for graph visualization, backlink navigation, and orphan detection |
Chat is the primary interface for day-to-day Brain usage — loading context, searching, editing files, committing. Cowork or Code are needed when the workflow requires direct filesystem access (e.g., saving source documents) or agentic multi-step operations. Code is the right tool for maintaining the server codebase itself.
For the full methodology, see the AI Brain Primer.
Related Projects
- ai-brain-primer — Framework and methodology for building an AI Brain
- ai-brain-jem — Example private Brain implementation (private repo)
License
MIT