How do I use Brain MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Brain MCP search my vault for notes about hybrid retrieval and give me a summary" 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.

Brain MCP

by Artur0927

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Brain MCP

MCP server for hybrid retrieval over a markdown vault: dense embeddings plus BM25, fused with RRF. Writes reindex the changed file. Optional shared embed process so each MCP session does not load models.

Compatible with any MCP stdio client.

Requirements


Python	3.11+
Docker Compose	v2 (Qdrant + embed service)
ripgrep	`rg` on `PATH`
RAM	~1.2 GB for ONNX models

Related MCP server: Datacron

Install

git clone https://github.com/Artur0927/brain-mcp.git
cd brain-mcp
bash scripts/deploy.sh

deploy.sh creates a venv, copies examples/sample-vault to ./vault if missing, starts Qdrant and the embed service, runs brain-index, and writes examples/mcp/mcp.generated.json.

First run downloads embedding models (~400 MB). Merge the generated mcpServers block into your MCP client config (see docs/setup.md).

Existing vault:

bash scripts/deploy.sh --vault /path/to/markdown

Architecture

flowchart LR
  Client(["MCP\nclient"]) <-->|stdio| Server

  subgraph core [" "]
    direction TB
    Server["brain-mcp\n12 tools · ~140 MB"]
    Server -->|encode| Embed["brain-embed :8091\nMiniLM-L12 + BM25"]
    Server -->|prefetch + RRF| Qdrant[("Qdrant :6333")]
    Server <-->|fs| Vault[("vault/")]
  end

Search flow: query → brain-embed encodes dense (384d cosine) + sparse (BM25 IDF) → Qdrant runs two prefetches (3x limit each) → RRF fusion → ranked chunks returned.

Write flow: file written to vault → chunked on headings (max 1500 chars) → old chunks deleted from Qdrant → new chunks embedded and upserted.

Process	Role	Bind
`brain-mcp`	MCP tools, vault I/O, Qdrant queries	stdio
`brain-embed`	Dense + sparse ONNX models, loaded once	`127.0.0.1:8091`
Qdrant	Hybrid vector collection	`127.0.0.1:6333`
`vault/`	Markdown source of truth	filesystem
`brain-reindex`	Incremental mtime-based reindex	systemd timer
`brain-dashboard`	Read-only Kanban + session logs	`127.0.0.1:8090`

Details: docs/architecture.md

Tools

Tool	Behavior
`brain_search`	Dense + sparse prefetch, RRF fusion; optional `path_prefix`
`brain_grep`	`rg` over the vault
`brain_read`	Read file by relative path
`brain_batch_read`	Up to 5 files per call
`brain_list`	Depth-limited listing
`brain_stats`	Collection size, disk, embed health, `.md` count
`brain_write` / `brain_append`	Mutate file, then reindex
`brain_log`	Append to `YYYY-MM-DD.md`
`brain_lesson`	Write `knowledge/agent-lessons/<stamp>_<agent>_<category>.md`
`brain_task_claim` / `brain_task_release`	File locks under `tasks/.locks/`

Server install

sudo bash scripts/deploy.sh --server --vault /data/vault

Installs under /opt/brain-mcp, enables brain-reindex.timer and brain-dashboard. Remote MCP over SSH: scripts/mcp-launcher.sh (ControlMaster). Config: docs/setup.md, .env.example.

Configuration

Variable	Default
`BRAIN_VAULT`	`./vault`
`BRAIN_COLLECTION`	`brain`
`BRAIN_QDRANT_HOST` / `BRAIN_QDRANT_PORT`	`127.0.0.1` / `6333`
`BRAIN_EMBED_URL`	`http://127.0.0.1:8091/embed`
`BRAIN_DASHBOARD_PORT`	`8090`
`BRAIN_AGENT_LOGS`	`./agentlogs`

CLI

brain-mcp             stdio MCP server
brain-embed           embedding HTTP service
brain-index           full reindex (recreates collection)
brain-reindex         mtime incremental reindex
brain-lessons-index   rebuild knowledge/agent-lessons/INDEX.md
brain-dashboard       HTTP UI

Operations

Symptom	Check
Tools missing in client	Reload MCP server; confirm `command` path in config
`embed_service: DOWN`	`docker compose ps`; `curl -s http://127.0.0.1:8091/`
Empty search	`brain-index`; `brain-stats`
`rg: command not found`	install ripgrep
Slow first start	model download
Port 8091 in use	`docker compose down` or `BRAIN_EMBED_PORT`

Layout

src/brain_mcp/        server, embed, indexer, dashboard
scripts/deploy.sh     local and --server install
examples/sample-vault template vault
examples/mcp/         mcp.json template
deploy/systemd/       units
docs/                 architecture, setup, agent protocol
docker-compose.yml    qdrant + embed

Agent boot/report convention: docs/agent-workflow.md.

Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

License

MIT

Available Tools

12 tools

brain_appendB

Append to a vault file. Auto-reindexes.

Inputs: path (required), content (required). Returns: result

brain_batch_readA

Read up to 5 vault files in one call.

Inputs: paths (required), max_chars. Returns: result

brain_grepB

Exact/regex search via ripgrep. Returns file:line:match.

Inputs: pattern (required), limit. Returns: result

brain_lessonB

Persist a reusable lesson under knowledge/agent-lessons/. Auto-reindexes.

Inputs: body (required), agent (required), category (required), context. Returns: result

brain_listB

List files in the vault with depth and pattern limits.

Inputs: path, depth, pattern. Returns: result

brain_logC

Timestamped daily log entry (YYYY-MM-DD.md). Auto-reindexes.

Inputs: agent (required), message (required), type. Returns: result

brain_readA

Read a vault file by relative path.

Inputs: path (required), max_chars. Returns: result

brain_searchB

Dense + BM25 prefetch, RRF fusion. Optional path_prefix narrows scope.

Inputs: query (required), limit, path_prefix. Returns: result

brain_statsA

Collection size, disk usage, embed service health, .md count.

Inputs: no named parameters. Returns: result

brain_task_claimC

Atomically claim a task for parallel agent coordination.

Inputs: agent (required), task_id (required), ttl_hours. Returns: result

brain_task_releaseA

Release a task claim if you own it.

Inputs: agent (required), task_id (required). Returns: result

brain_writeA

Create or overwrite a vault file. Auto-reindexes.

Inputs: path (required), content (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-08-31 21:30 across 12 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: grep and search differ by exact/regex vs semantic search; read and batch_read differ by count; write, append, log, and lesson each target different write behaviors and destinations. The task claim/release pair is also unambiguous in ownership semantics.

Naming Consistency4/5

Most tools follow a consistent brain_<verb> pattern such as brain_read, brain_write, brain_append, and brain_list. Minor deviations like brain_stats, brain_lesson, and brain_task_claim/task_release introduce nouns or object-verb ordering, but the overall pattern remains predictable.

Tool Count5/5

Twelve tools is well within the ideal range and matches the server's dual purpose of knowledge vault management and agent task coordination. Each tool covers a meaningful operation without unnecessary redundancy or feature bloat.

Completeness3/5

Core vault operations like search, read, write, append, list, and specialized logging are covered well. However, there is no delete/remove or rename/move tool, and task coordination lacks a way to discover or list tasks, which can create dead ends in some workflows.

Maintenance

ActivityStale

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

trip2gB
io.github.trip2g
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
RAG Systems Note Taking Search
12240
https://trip2g.com/_system/mcp
hjarniA
com.hjarni
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Knowledge & Memory Note Taking Workplace & Productivity
4131
https://hjarni.com/mcp
Valta
si.valta
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Note Taking Knowledge & Memory
1
https://valta.si/mcp
NeuroStack
io.github.raphasouthall
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Knowledge & Memory RAG Systems Vector Databases
247
https://mcp.neurostack.sh/mcp

Related MCP Servers

Markdown Notes MCP
Note Taking Search RAG Systems
codeMaestro78
F
license
Not graded
quality
D
maintenance
Enables managing and searching markdown notes with semantic search, question answering, and note generation, and provides an MCP server for GitHub Copilot integration.
Updated a year ago (2025-09-13 23:24 UTC)
4
-
Datacron
Note Taking Knowledge & Memory Search
VBlackJack
A
license
A
quality
B
maintenance
Local MCP server for querying and maintaining a Markdown vault. Provides full-text search, backlinks, note retrieval, and optional confined write tools, without sending the whole vault to the client context.
Updated 8 days ago (2026-11-03 08:40 UTC)
22
61 PyPI
1
Apache 2.0
ragmark
RAG Systems Knowledge & Memory Note Taking
cdcoonce
A
license
Not graded
quality
B
maintenance
Local-first MCP server for retrieval over markdown wikilink vaults, offering hybrid vector+lexical search, note reading, neighbor expansion, and recent activity tracking with fully local embeddings and no network egress.
Updated a month ago (2026-10-11 10:17 UTC)
MIT
vault-search-mcp
RAG Systems Note Taking Search
everton-dgn
A
license
B
quality
B
maintenance
Enables local hybrid search over Obsidian and Markdown vaults via MCP, combining vector retrieval, full-text search, reranking, graph navigation, and safe CRUD while keeping data local.
Updated 9 days ago (2026-11-02 13:36 UTC)
43
1
MIT

Brain MCP

Requirements

Install

Architecture

Tools

Server install

Configuration

CLI

Operations

Layout

Development

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Markdown Notes MCP

Datacron

ragmark

vault-search-mcp