brain-graph MCP server
Commit Oct 17, 2026Enables AI clients to query a Neo4j graph index built from wikilinked markdown notes to traverse knowledge connections.
Also known as DimeDataCloud/brain-graph
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 17, 2026
- License
- MIT
What is brain-graph MCP?
brain-graph enables AI clients to query a Neo4j graph index built from wikilinked markdown notes to traverse knowledge connections.
Summary generated from the project's README
About brain-graph MCP server
Traversing connections within a markdown knowledge base is what brain-graph enables for developers using AI clients like Claude. By indexing folders of wikilinked markdown notes into a Neo4j database, this tool allows an AI to understand the relationships between your notes rather than just performing simple text searches. It is designed for users with Obsidian vaults, team wikis, or AI agent memory folders.
The system works by parsing markdown files and their [[wikilinks]] to build a graph of nodes and edges. Users set up the environment using Docker for Neo4j and configure the server via a .env file containing a NEO4J_PASSWORD and GRAPH_SOURCES. The MCP server runs locally via stdio and provides a read-only interface, ensuring the markdown files remain the single source of truth.
Through specific tools, the server can find the shortest path between two notes, identify neighbors within three hops, or locate orphan notes. It also provides graph statistics and allows for read-only Cypher queries. This setup transforms a collection of files into a navigable web of knowledge that an AI can explore to find deep connections.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledimedatacloud/brain-graph is public and reachablegithub.com/dimedatacloud/brain-graph ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-17github.com/dimedatacloud/brain-graph ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOverview
brain-graph reads a folder of markdown notes linked with [[wikilinks]]. An Obsidian vault, a team wiki and
an AI agent's memory folder all fit this shape. It writes the notes and their links into Neo4j, then exposes
the graph through a read-only MCP server.
Grep answers "which files mention Acme". brain-graph answers "what is connected to Acme, and how far away is
it". Every sync also lists orphan notes, dangling links and notes missing a level: field.
It is for people who keep a markdown knowledge base and want an AI client to traverse it, not just search it.
flowchart LR
V[(markdown vault<br/>one or more)] -->|graph-lib.mjs<br/>parse · resolve| S[graph-sync.mjs]
S -->|full rebuild per source| N[(Neo4j)]
S -->|stdout| R[report:<br/>orphans · dangling links · missing level:]
N -->|read-only session| M[mcp-server.mjs]
M -->|stdio| C[Claude / any MCP client]
Quick start
Requires Node 20.6 or newer (for --env-file) and Docker.
npm install
npm run verify # assertions against the bundled example-vault/
npm run dry # parse example-vault/ and print the report. No database needed.
The dry run prints a report like this (trimmed):
sources : brain
nodes : 12 (8 governed by the orphan/level rules)
edges : 12
orphans : 1 (12.5% of governed)
dangling : 1 (wikilinks pointing at nothing)
missing level: 2 (25.0% of governed)
...
DANGLING WIKILINKS (target does not exist, fix the link or write the note):
brain:ideas/someday -> [[ideas/not-written-yet]]
Then point it at your own vault and write the graph:
cp .env.example .env # set NEO4J_PASSWORD and GRAPH_SOURCES
npm run up # Neo4j 5 with APOC; browser UI on http://localhost:7474
npm run sync
Sync is a full rebuild. It deletes every node whose
sourcematches a name inGRAPH_SOURCESand writes them again. Do not share a source name with anything else living in the same database.
Connect Claude
Add the server to .mcp.json (Claude Code) or your client's MCP config:
{
"mcpServers": {
"brain-graph": {
"command": "node",
"args": ["/path/to/brain-graph/mcp-server.mjs"]
}
}
}
It reads NEO4J_PASSWORD from the environment or from the .env file beside it.
| Tool | What it answers |
|---|---|
entity_neighbors |
Everything within 1 to 3 hops of a note |
shortest_path |
How two notes relate, as a chain of slugs |
find_orphans |
Notes with no links in or out |
recent_by_type |
Most recently updated notes with a given label |
graph_stats |
Counts by label and edge type, orphans, notes missing level: |
query_graph |
Any read-only Cypher |
Every Cypher statement is checked for write clauses before it reaches the driver, and the session is opened in read mode.
Configuration
Set these in .env. Names only here; never commit real values.
| Variable | Required | Default | Purpose |
|---|---|---|---|
NEO4J_PASSWORD |
yes | none | Password for the neo4j user. Used by Docker Compose, graph-sync and the MCP server. |
NEO4J_URI |
no | bolt://localhost:7687 |
Bolt address of the Neo4j instance. |
NEO4J_USER |
no | neo4j |
Neo4j user name. |
GRAPH_SOURCES |
no | bundled example-vault |
Comma-separated name=path pairs. Each name becomes the source of its nodes. |
GRAPH_GENERATED |
no | none | Slugs of machine-generated notes, exempt from the orphan and level: rules. |
GRAPH_DATA_DIR |
no | ./.neo4j |
Where the Neo4j container keeps its data. Keep it outside any synced folder. |
What becomes a node and an edge
- Nodes. Every
.mdfile, keyed by its path without the extension (builds/example-app). Its label comes from frontmattertype:, or failing that from its top folder (people/becomesPerson,companies/becomesCompany; the table isFOLDER_TYPEingraph-lib.mjs).INDEX.mdfiles are labelledIndex. Scripts (.sh,.mjs,.ps1) undersystems/orscripts/become nodes too, so links to them resolve. LINKS_TOedges. Every[[wikilink]]in a note's body. Links inside code spans, fenced blocks and HTML comments are ignored, so a note that documents the link syntax does not link to a note called "wikilink".- Typed edges.
company:becomesWORKS_AT,client:becomesFOR_CLIENT,supersedes:becomesSUPERSEDES, anduses_skill:becomesUSES_SKILL. A field only becomes an edge when its value is written as a wikilink (company: "[[companies/acme]]").client: internalstays plain text. - Resolution. For each link the resolver tries, in order: the exact slug, a case-insensitive match,
an alias declared on the target (
aliases:,alias:orslug:), the folder'sREADME,INDEXorSKILLnote, then a basename that matches exactly one note. When two notes match, the link is reported as dangling rather than guessed, because a wrong edge is worse than a reported one. - Exempt from the rules.
skills/**, anything with a_-prefixed path segment, and the slugs inGRAPH_GENERATEDare indexed but never reported as orphans or as missinglevel:. Dot-folders are not read.archive/agent-outputs/andbackups/are indexed as single nodes, and their contents are never parsed.
Each vault in GRAPH_SOURCES is resolved on its own. A link in one vault never resolves to a note in another.
Design notes
- The markdown is the source of truth. The graph is derived from it and rebuilt from scratch on every sync. If the graph and the files disagree, run the sync again rather than editing the graph. This is why the MCP server cannot write.
- No YAML dependency. The frontmatter reader handles flat
key: valuepairs and lists, which covers how notes are actually written. - CRLF is tested. In JavaScript,
$does not match before a\r. A regex-based frontmatter parser returned nothing for every CRLF file and reported no error, so a vault checked out on Windows gave different answers than on Linux.verify.mjschecks that both line endings parse identically, and.gitattributeskeeps the CRLF fixture CRLF.
Project structure
brain-graph/
├── graph-lib.mjs # Parsing, link resolution and node/edge mapping
├── graph-sync.mjs # Full rebuild of the graph, and the report
├── mcp-server.mjs # Read-only MCP server (stdio)
├── verify.mjs # Assertions run against example-vault/
├── docker-compose.yml # Neo4j 5 with APOC
├── example-vault/ # Bundled sample vault used by verify and dry run
└── .env.example
Testing
npm run verify
verify.mjs runs its assertions against example-vault/, covering parsing, link resolution, LF and CRLF
handling and the report. It does not need a running Neo4j instance.
Contributing
Issues and pull requests are welcome. Please run npm run verify before opening a pull request.
License
Released under the MIT License. See LICENSE. Built by Dime Data.
brain-graph MCP questions
Is the MCP server read-only?
Yes, the server is read-only to ensure the markdown files remain the single source of truth.
How is the graph updated?
The graph is a full rebuild that deletes existing nodes for a source and rewrites them from the markdown files during a sync.
What are the requirements to run it?
You need Node 20.6 or newer and Docker.