Connecting from an AI assistant (MCP) Added in v0.46.0 (2026-08-28)
Graphium can act as an MCP server, which means an AI assistant that lives outside Graphium — Claude Desktop, Claude Code, or any other MCP client — can look inside your notes and add new ones.
This is the opposite direction from MCP servers in Setting up AI
That page is about Graphium as the client, calling out to other tools from its own AI chat. This page is about Graphium as the server, with an outside assistant calling in to your notes. They are independent: use either, both, or neither.
Instead of opening Graphium, finding the right note, and copying a procedure into a chat window, you ask the assistant directly:
"What conditions did I use when I ball-milled CuGaTe2?"
and it reads the answer out of your own notes, with the note it came from.
What this is good for
- Asking your own notes questions. Your assistant searches your vault instead of guessing from general knowledge.
- Comparing your own experiments. "Which of my runs used a graphite die?" is a question your notes can answer and a general-purpose model cannot.
- Pulling a procedure into a conversation. Steps come back in order, with the materials, tools and conditions attached to each one.
- Saving a conclusion back. When a conversation produces something worth keeping, the assistant can write it into your vault as a new note.
Your notes never leave your machine except as answers the assistant reads. Graphium does not have to be running — the server reads your note files directly, so it works with the app closed.
Setting it up
You need Node.js 20 or later and a copy of the Graphium source.
1. Build the server. In the Graphium folder:
pnpm install
pnpm bundle:mcpThis produces a single file at dist-mcp/graphium-mcp.mjs.
2. Tell your client about it. For Claude Desktop, open Settings → Developer → Edit Config and add a graphium entry:
{
"mcpServers": {
"graphium": {
"command": "node",
"args": ["/absolute/path/to/Graphium/dist-mcp/graphium-mcp.mjs"]
}
}
}Use the full path, not a relative one. For Claude Code, run claude mcp add graphium -- node /absolute/path/to/Graphium/dist-mcp/graphium-mcp.mjs instead.
3. Restart the client. Claude Desktop needs a full restart, not just a new conversation.
Other MCP clients
Nothing here is specific to Claude. Graphium speaks the standard protocol over stdio, so any client that can launch a local MCP server works — Cursor, VS Code, Zed, Cline, and others. What every one of them needs is the same two pieces: the command node, and the absolute path to graphium-mcp.mjs.
Where you put that differs by client, and these settings move around between versions, so check your client's own MCP documentation for the exact location and shape. Many accept the mcpServers JSON above as-is.
| Client | How to add it |
|---|---|
| Claude Desktop | Settings → Developer → Edit Config |
| Claude Code | claude mcp add graphium -- node <path> |
| Cursor, VS Code, Zed, Cline, … | Their own MCP settings — usually the same JSON shape |
Two limits worth knowing: the server runs as a local process (there is no hosted URL to point at — remote HTTP transport is not supported), and it needs Node.js 20+ on the machine running the client. Since your notes stay on your disk, the client has to be on the same machine as your vault.
By default the server reads ~/Documents/Graphium. If you changed the Graphium folder in ⚙ Settings → General, the server follows that setting automatically. To point it somewhere else explicitly, add an env block:
{
"mcpServers": {
"graphium": {
"command": "node",
"args": ["/absolute/path/to/Graphium/dist-mcp/graphium-mcp.mjs"],
"env": { "GRAPHIUM_ROOT": "/Users/you/Dropbox/Graphium" }
}
}
}What the assistant can do
Seven tools are available. You do not call them by name — you ask in plain language and the assistant picks.
| Tool | What you would ask |
|---|---|
search_notes | "Find my notes about thermoelectric measurements" |
get_note | "Show me that note" |
get_note_steps | "What were the steps, with the conditions?" |
find_notes_using | "Which experiments used a planetary ball mill?" |
list_entities | "What materials and instruments show up across my notes?" |
trace_lineage | "Where did this conclusion come from?" |
create_note | "Save this as a note" |
Search covers titles, body text, step names and labels, and works in Japanese without spaces between words — the same segmentation the app itself uses, so a query that finds something in Graphium finds it here too.
Every answer carries the note id and the block id, so the assistant can tell you exactly where something came from and you can open that spot in Graphium.
What an answer looks like
Asking for a procedure gives you the steps in order, with what each one used:
# 多結晶CuGaTe2のボールミリング条件と熱電特性 の手順（9 件）
1. 溶融 [blockId: 801e35ed-…]
material: Cu, Ga, Te
tool: シリカ管
attribute: 99.99%, 99.999%
純度99.99%のCu、純度99.99%のGa、純度99.999%のTeをシリカ管に封入し、直接反応によって溶融する。
3. ボールミリング [blockId: b2cd7d10-…]
material: 粉末
tool: プラネタリーボールミル, WC ボール
attribute: rpm: 300, ball-to-powder ratio: 2:6:1, atmosphere: Ar, time: 0 hAsking which notes share an instrument gives you the set, with the block in each:
■ tool: グラファイトダイ — 3 ノート
- 多結晶CuGaTe2のボールミリング条件と熱電特性 [noteId: 70ac6b8a-…, blockId: 540904a1-…]
- CuGaTe2 のボールミリング条件が熱電特性に与える影響 [noteId: 585e605f-…, blockId: d22a6e98-…]Things worth asking
You never name a tool — ask in plain language and the assistant picks. These work well:
- "Which of my experiments used a graphite die?" — the comparison you cannot get from a general-purpose model, because it needs your records
- "Walk me through the CuGaTe2 ball-milling procedure, with the conditions for each step." — pulls a procedure into the conversation so you can adapt it
- "What instruments and materials show up across my notes?" — a way to see the shape of what you have recorded
- "I ran this at 873 K instead. How does that compare to what I did before?" — your own notes as the baseline
- "Where did this conclusion come from?" — follows the provenance back to the notes it was derived from
- "Save what we just worked out as a note titled …" — writes the conversation's outcome into your vault
A good habit is to ask for the note it used. The assistant has the ids, so "which note is that from?" always has an answer, and you can open it in Graphium to check.
Labels make it much better
find_notes_using and list_entities read the material / tool / condition / output highlights you put in your notes. If you have not labelled anything yet, those two tools have nothing to work with — search and the other five still work fine.
This is the payoff of labelling: once a handful of notes name the same instrument, "which of my experiments used this?" becomes a question you can just ask. See Labels & provenance.
What it deliberately does not do
It never edits your existing notes. create_note only adds new ones. Nothing an assistant does through MCP can overwrite something you wrote.
It never invents provenance. You might expect that chatting about an experiment would build the provenance graph for you. It does not, and this is on purpose. Provenance is a record of what actually happened. A graph reconstructed from a conversation would look the same but mean something different — a guess about your procedure, with nothing to check it against. Graphium records provenance from what you did in the editor, not from what a model inferred you probably did.
What is recorded automatically is the write itself. A note created through MCP carries who asked for it, which client it came through, and which model wrote it. That is an observation, not an inference.
Notes created through MCP appear after a reload. The note list is built by the app, so a note written while Graphium is open shows up the next time you reload or restart it.
Troubleshooting
The client shows no Graphium tools. Check the path in the config is absolute and points at an existing graphium-mcp.mjs, then fully restart the client. In Claude Desktop, Settings → Developer shows whether the server started.
Tools answer "vault not found". The server could not find your notes folder. Set GRAPHIUM_ROOT in the env block to the folder that contains notes/.
Search finds nothing in a vault that has notes. The server builds its own search index on first use, which takes about a second on a large vault. If it stays empty, check that the folder you pointed at is the one Graphium actually saves into — ⚙ Settings → General shows the current path.
See also
- Labels & provenance — the labels that
find_notes_usingreads - Storage & sync — where your notes live on disk
- Setting up AI — Graphium's own built-in AI, which is separate from this