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, add new ones, and help maintain the knowledge layer.
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.
- Reading the source itself. The assistant can read the text of a PDF (by page), a Word file, or a web page you have registered in Graphium, instead of relying on what a topic says about it.
- Seeing a procedure as a diagram. The steps of a note come back as a Mermaid flowchart you can paste into a document.
- Maintaining knowledge pages. The assistant can merge duplicate topics, rewrite a topic or Q&A page, or archive one. Every change is recorded and can be undone from Graphium.
Your notes never leave your machine except as answers the assistant reads. Reading, searching and adding notes work whether Graphium is open or closed — the server reads your note files directly. The one exception is maintaining knowledge pages: quit Graphium first. While the app is running it treats its own index as the truth, so a change made from outside would not show up until the next start and could be overwritten; the server refuses with APP_RUNNING: instead.
Setting it up
There are three steps: build the server once, register it with the app you use, then check that it answers. After that you just talk to your assistant as usual.
You need:
- Node.js 20.16 or later (needed by the PDF reader, pdfjs)
- The Graphium source (the desktop app download does not include the MCP server, so you build it from source)
- pnpm (
npm install -g pnpmif you don't have it)
1. Build the server. Get the source and run this in its folder:
git clone https://github.com/kumagallium/Graphium.git
cd Graphium
pnpm install
pnpm bundle:mcpThis produces a single file at dist-mcp/graphium-mcp.mjs. You will need its full path in the next step (the folder pwd prints, followed by /dist-mcp/graphium-mcp.mjs).
The bundle reads the PDF and Word text readers from the clone's node_modules, so if you copy graphium-mcp.mjs somewhere else and run it there, only those two (PDF and Word text) stop working — every other tool still works. Keep the file where pnpm bundle:mcp put it.
Note down the full path of node itself too. Desktop apps don't always inherit your terminal's PATH, so "command": "node" on its own can fail to start — especially if you installed Node with nvm.
which node2. Register it with your app.
Claude Code — run this in a terminal. --scope user makes your Graphium notes available whichever folder you open Claude Code in; without it, the server is only registered for the folder you ran the command in.
claude mcp add --scope user graphium -- /path/to/node /path/to/Graphium/dist-mcp/graphium-mcp.mjsClaude Desktop — add a graphium entry under mcpServers in the config file that Settings → Developer → Edit Config opens (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"graphium": {
"command": "/path/to/node",
"args": ["/path/to/Graphium/dist-mcp/graphium-mcp.mjs"]
}
}
}Quit Claude Desktop before you edit the file
The same file also holds the app's own settings. If you edit it while the app is running, the app can write its in-memory copy back when it quits or restarts, and your graphium entry disappears. Quit the app completely (⌘Q, or quit from the system tray on Windows), edit and save the file, then start the app again. Leave everything else in the file (other servers under mcpServers, preferences) as it is and only add graphium.
Use full paths in both cases, not relative ones.
3. Check that it works. Claude Desktop needs a full restart, not just a new conversation; in Claude Code, start a new session. Then ask:
What topics are in my notes?
If you get a list of topics back, you are done. In Claude Code, claude mcp list also shows whether graphium is ✓ Connected.
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.16+ 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" }
}
}
}Updating to a newer version
The MCP server keeps running the Graphium version you built it from — the desktop app's auto-update does not touch it. After updating the source, rebuild and restart your app:
cd Graphium
git pull
pnpm install
pnpm bundle:mcpYou don't need to register it again; the file at the same path is simply replaced. If a tool listed below is missing from your assistant, a forgotten rebuild is the usual reason.
What the assistant can do
These 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?" / "Draw this procedure as a diagram" (format: "mermaid" returns a flowchart) |
find_notes_using | "Which experiments used a planetary ball mill?" |
list_entities | "What materials and instruments show up across my notes?" |
list_topics Added in v0.76.0 (2026-09-16) | "What topics has Graphium worked out from my notes?" |
get_topic Added in v0.76.0 (2026-09-16) | "Tell me what you know about sintering conditions" (returns the body and the names of the sources it cites) |
trace_lineage | "Where did this conclusion come from?" / "Which notes came from this PDF?" |
create_note | "Save this as a note" |
save_answer Added in v0.79.0 (2026-09-18) | "Keep this answer for later" |
export_prov Added in v0.87.0 (2026-10-07) | "Give me this note's provenance as PROV-DM (W3C PROV JSON-LD)" |
get_source_text Added in v0.87.0 (2026-10-07) | "Read page 3 of that PDF" / "What does the source actually say?" |
search_media Added in v0.87.0 (2026-10-07) | "Which PDF did I import about sintering?" / "Where is the figure with the phase diagram?" |
check_knowledge Added in v0.87.0 (2026-10-07) | "Are there duplicate or empty topics?" (mechanical checks only) |
list_source_check Added in v0.87.0 (2026-10-07) | "Which pages did source check flag as needing review?" |
list_todos Added in v0.94.9 (2026-10-22) | "Is there anything I still have to do?" / "What's left unchecked in the battery folder?" (unchecked checklist items across your notes, with the note and block ids — see below) |
revise_topic Added in v0.87.0 (2026-10-07) | "Rewrite this topic with the new result" |
merge_topics Added in v0.87.0 (2026-10-07) | "Merge these duplicate topics into one" |
archive_page Added in v0.87.0 (2026-10-07) | "Archive the topics we no longer need" |
restore_page Added in v0.87.0 (2026-10-07) | "Bring that page back from the archive" |
list_operations Added in v0.87.0 (2026-10-07) | "What upkeep operations have been done recently?" |
undo_operation Added in v0.87.0 (2026-10-07) | "Undo that merge" |
start_claim_task Added in v0.97.0 (2026-10-26) | "Turn this note into claims" (the assistant writes the claims itself; see below) |
submit_claims Added in v0.97.0 (2026-10-26) | Called by the assistant after start_claim_task, with the claims it wrote |
find_claims_for_task Added in v0.97.0 (2026-10-26) | Called by the assistant to look for more existing claims it might add to |
submit_rewrite Added in v0.97.0 (2026-10-26) | Called by the assistant to tidy a claim it added to (optional) |
start_insight_task Added in v0.98.0 (2026-10-27) | "Look for insights across my claims" (the assistant writes the insights itself; see below) |
submit_insights Added in v0.98.0 (2026-10-27) | Called by the assistant with the insights it wrote. Nothing is saved yet; it returns a review task |
submit_insight_review Added in v0.98.0 (2026-10-27) | Called by the assistant with the review's answers. The insights are saved here |
mark_asterism_sent Added in v0.95.0 | "Record the claims Asterism accepted" (then export_asterism_claims with onlyUnsent: true leaves out what was already sent) |
list_media Added in v0.95.0 | Not something you ask for — another app (such as Asterism) calls it to list the files among your materials, filtered by extension (see below) |
get_media_file Added in v0.95.0 | Another app fetches one material's file (name, MIME type, size and, on request, the bytes) |
add_material Added in v0.95.0 | Another app puts a file into your materials. The same content is never added twice; it gets the existing material's id back |
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.
Using your materials from another app Added in v0.95.0
Three tools are made for other programs rather than for you: list_media, get_media_file and add_material. They let an app that reads tables (for example Asterism) use Graphium as the place where the original files live — it lists your CSV and Excel files, pulls one in, and, when you drop a table into that app directly, sends the original back so it also appears among your materials. Unlike the other tools, these answer in JSON, which is what programs read.
A few things to know:
add_materialonly accepts the file's content (base64). It never reads a path on your disk, so a connected assistant cannot use it to pick up arbitrary files.- The same content is never stored twice. The check is the file's SHA-256, the same key the app uses, so a renamed copy still merges with the material you already have.
- Files over 32 MiB are not fetched or added through these tools.
- A material added this way shows up in Graphium, and in
list_media, after Graphium next rebuilds its media index (restarting Graphium is the sure way). Until then, dropping the same file in the app may create a second copy. - Folders cannot be set yet; added files land in the top level of your materials.
create_note: formulas, superscript and subscript
The body is Markdown: headings, lists, code blocks, tables, bold, italic, inline code and links, plus formulas and superscript / subscript. These use the notation get_note uses when it hands a note to the assistant: $…$ for a formula inside a sentence, $$ … $$ on a line of its own for a displayed formula, and <sup> / <sub> for 10⁵ or H₂O. So when the assistant quotes one of your notes into a new one, $x$ and <sup>5</sup> are saved as a formula and a superscript rather than left as raw text. Prices are left alone: $100 and $200 or $50-$75 stay text.
create_note: citations
create_note takes two optional arguments beyond title and body:
citations— a list of{ id, title? }referring to Graphium notes or pages the answer drew on. When present, a References section is appended to the note body: an entry whoseidmatches an existing note becomes an@-linked reference (same shape as the References section topics build from their sources); an entry whoseiddoes not resolve is kept as plain text instead of being silently dropped.
Both arguments are additive — a call without them behaves exactly as before.
create_note vs. save_answer
Both tools write something new into your vault, but into different layers, and Graphium treats each layer differently afterwards:
create_notewrites a note — something a human maintains. Graphium never touches it again on its own.save_answerwrites a Q&A page — a knowledge-layer page (the sameanswerkind the in-app "Keep as knowledge" button on a chat message produces). Once it exists, Graphium revises it whenever related material is ingested, and includes it in linting and source-check like any other knowledge page. One difference from the in-app button: "Keep as knowledge" rewrites the exchange into a standalone article before saving (it has the conversation to draw on);save_answersaves thequestion/answeryou pass exactly as given, since Graphium has no access to the rest of your conversation with the external client. Write the body so it already reads standalone.
Use save_answer for something you expect Graphium to keep maintaining as your notes grow; use create_note for a one-off record you will maintain yourself.
In the body you pass to save_answer, end every grounded sentence with [[source:<id>]] (the ids you pass in citations; list several when several sources say the same thing). Source check works sentence by sentence — it asks whether the sources a sentence cites really say it — so a Q&A page with no citations in its body is never checked. Save one without them and the tool says so in its reply.
save_answer takes:
question— becomes the page title.answer— the body (Markdown). Write[[source:<id>]]inline where the answer cites something in your vault.citations— a list of{ id, title? }, the same shape ascreate_note's. Each[[source:<id>]]inansweris resolved against this list, and a References section is appended. Anidthat matches an existing note or page becomes an@-linked reference; anidthat does not resolve is kept as plain text.sessionId,model— same ascreate_note, recorded for provenance.
After save_answer returns, the page appears in Graphium after a reload, same as a note from create_note.
Reading a source Added in v0.87.0 (2026-10-07)
get_source_text returns the text of a source, cut into windows so a long document comes back a piece at a time (default 4,000 characters, with a 400-character overlap between windows). To continue, the assistant asks for the next window.
- PDF — each window says which pages it covers ("pages n–m"), and you can ask for a page directly ("read around page 3") to get the window that contains it.
- Word —
.docxfiles only. Other formats (.xlsx,.pptx, the old.doc) answerUNSUPPORTED_FORMAT. - Web page — only a URL already registered in Graphium. The text is fetched again from the network at that moment, so it is the page as it is now, not the copy Graphium saved when you imported it.
- Note — a note id returns the note's text.
The id of a source appears in get_topic and search_media (pdf:… / document:… / url:…), so the assistant can go from "what does this topic cite" to "read that source" without you looking anything up.
Maintaining knowledge pages from your assistant Added in v0.87.0 (2026-10-07)
The assistant can look after the knowledge layer the way you would from Upkeep. This applies to topics and Q&A pages only — notes, claims and insights are never touched.
| Tool | What it does |
|---|---|
revise_topic | Rewrites the body (Markdown). End each grounded sentence with [[source:<id>]]. Any source id you pass must exist in Graphium, otherwise it answers UNKNOWN_SOURCE. If you pass no sources, the page keeps its current ones |
merge_topics | Merges topics into one. You pass the body of the topic that stays; the absorbed topics go to the Trash |
archive_page / restore_page | Archives a page, or brings one back from the archive or Trash |
list_operations | Lists recent upkeep operations, including ones done in the app, with whether each can be undone |
undo_operation | Undoes one operation. It first returns an estimate of what would change. If a page was edited after the operation, or source check results would also go back, you have to repeat the call with confirm: true |
How this stays safe:
- Every change is recorded and can be undone. Operations appear in Graphium under Upkeep → Operations as MCP (client name), next to the ones you started in the app, and you can undo them from there too (see Upkeep operations can be undone). An undo done through MCP is itself recorded and can be undone.
- No version is made. The History panel does not get a version for a change made through MCP. To go back, use the Operations record (the copies it keeps last one year).
restore_pageis not recorded, the same as un-archiving in the app.- Quit Graphium first. While the app is running these tools answer
APP_RUNNING:and change nothing. - Two MCP clients writing at once — the second one answers
BUSY:until the first finishes. - A vault Graphium has never opened has no
note-index.json, and these tools answerNO_INDEX:. Start Graphium once, quit it, and try again. - An old-format topic (one built from claims) answers
OLD_FORMAT:. Open it in Graphium and use Rebuild from sources to bring it to the new format first.
The changes show up the next time you start Graphium. Two things catch up only later: the "used in notes" list on a source, and semantic search (embeddings) for that page, which update the next time you save or re-embed the page in the app.
Having your assistant make claims Added in v0.97.0 (2026-10-26)
Your assistant can make claims from a note, a memo or a material (PDF, Word .docx, or a web page you registered) — the same thing Add to knowledge does in the app, but with the assistant's own model instead of the one set up in Graphium. If you already pay for a strong model in Claude or another assistant, Graphium does not need an AI of its own for this.
The assistant does not write claim pages freely. It takes part in Graphium's own step:
start_claim_taskhands the assistant the same instructions the app would send to its own model, together with the note's text and a list of related existing claims.- The assistant writes the claims and passes them to
submit_claims. - Graphium checks them the way it checks its own model's output and saves them.
You only ask — "turn this note into claims" — and the assistant calls the tools in order.
What stays with Graphium:
- Where a claim came from. A claim's source is always the note or material the task was for. Whatever the assistant writes, it cannot name a different source.
- Adding to an existing claim. The assistant can add to an existing claim only when Graphium listed it in the task. The task lists about a hundred related claims; if the right one is not there, the assistant can look for more with
find_claims_for_task. - The same checks as the app. Fields outside Graphium's vocabulary are dropped, a decision or rule that cannot be found word for word in the note is dropped, and a claim backed by two independent sources becomes Corroborated, as in the app.
- Who made it. The page records that it came through MCP, from which client, and the model name the assistant gave. Graphium cannot check that name.
When the assistant adds to an existing claim, the new part is appended right away, and the assistant gets an optional task to tidy the page as a whole (submit_rewrite). Leaving it untidied loses nothing.
Things to know:
- "Use claims" must be on. If it is off in Settings → AI → Experimental features, the tools answer
CLAIMS_DISABLED:. If the vault has never been opened by this version of Graphium, they answerSETTINGS_UNKNOWN:— start Graphium once and quit it. - Quit Graphium first, as with maintenance: while it runs the tools answer
APP_RUNNING:. - Each submission can be undone in one step. It appears under Upkeep → Operations as Created claims via MCP. Undoing it moves the claims it made to the Trash and puts back the ones it added to.
- Semantic search catches up on the next start. Graphium adds the embeddings for these pages a few seconds after it starts.
- Long material is cut, as in the app. A PDF or Word file past about 80,000 characters is cut to fit one task. A web page is read again when the task is made.
- Topics are not made this way yet. They still come from Graphium's own ingest. Insights can be — see the next section.
- The note's text is material, not instructions. The task tells the assistant not to follow anything written inside the note.
Having your assistant make insights Added in v0.98.0 (2026-10-27)
Your assistant can also look for insights across your claims, again with its own model. As with claims, it takes part in Graphium's own step rather than writing pages freely, but there are two rounds instead of one:
start_insight_task— Graphium picks a bundle of 50 related claims and hands the assistant the same instructions it would send to its own model.submit_insights— the assistant passes the insights it wrote. Nothing is saved yet. Graphium returns a review task with the same four checks the app runs: whether an example from another field really has the same shape, whether the claims bundled into one insight really belong together, a plain-language rewording, and whether an insight repeats or contradicts one you already have.submit_insight_review— the assistant passes the review's answers, and Graphium saves the insights.
You only ask — "look for insights across my claims" — and the assistant calls the tools in order.
The review is the point of the second round. In the app, the same model reviews its own insights in a separate call that does not see how they were written. The review task gives the assistant only the items to check, and asks it to review in a separate context — a sub-agent, for example. Graphium cannot check that it did. Every check in the task needs an answer; an empty answer is allowed, and is treated the way the app treats a failed check (the example from another field is dropped, the bundle is kept, the wording stays, and the insight is saved as new).
What stays with Graphium:
- Which claims an insight rests on. Only claims from the bundle can be its sources, and its certainty is the lowest of theirs.
- How much has been looked at. Each answer reports coverage — how many of your claims have been looked at so far, out of all of them. A bundle counts only once the assistant has answered it. Ask again to continue; when every claim has been looked at, the next round starts.
- Repeats and contradictions. An insight the review marks as the same as an existing one adds its claims to that insight instead of making a new page. One it marks as contradicting is kept as a separate insight, linked to the other both ways, and shows up as a Contradiction in Upkeep → Check.
Things to know:
- "Use insights" must be on, in Settings → AI → Experimental features (it also needs "Use claims"). Otherwise the tools answer
INSIGHTS_DISABLED:. - Quit Graphium first, as with maintenance.
- Each review can be undone in one step, as Created insights via MCP under Upkeep → Operations. Undoing it moves the new insights to the Trash and puts back the ones it added to or linked.
- Bundles and repeats are found by wording, not meaning. The app uses semantic similarity (embeddings) for both; outside the app there are none, so a reworded repeat can be missed and saved as a new insight. Graphium's full check can still find it as redundant later.
Your to-dos and task tools Added in v0.94.9 (2026-10-22)
Graphium is a place to keep records, not a task manager. There is a line here, and it is worth knowing where it runs.
A checklist in a note is part of the record: "I confirmed this", "this is still open". It has one bit — checked or not — and nothing else. A task in a task manager is something that gets picked up, changes state, has a due date and an owner, and can be cancelled rather than deleted. Graphium stores none of that state, on purpose: state has to be kept up to date or it turns into a lie, while a record only has to be true once.
What list_todos gives an assistant is the first kind: every checklist item across your notes that is not yet checked, with the note and block it lives in, in the order it appears. If you wrote a date or a link in the item's text, the assistant sees it — Graphium does not interpret either. So "what's due this week?" works, but the ordering happens in the conversation, not in Graphium.
If you keep your tasks in a tool that also speaks MCP, connect both to the same assistant and the bridge is already there: "turn the open items in this note into tasks", "which of this week's tasks have a note behind them?". Paste the task's link into the checklist item and the two stay matched. Graphium does not know which tool you use, and does not need to — nothing in it is specific to any task manager.
What it will not do, by design: tick an item off (the check mark in your note is yours — it says you confirmed it, not that another tool did), add an item from outside, or hold a due date, a priority or an owner. If you want those, that is what the task tool is for.
Notes vs. knowledge
Graphium builds a knowledge layer on top of your notes: claims (findings extracted from a note, with their source attached), topics (a page that gathers what your sources say about one concept), and insights (a pattern that spans two or more claims). search_notes can filter by kind — note, topic, claim, insight, or wiki for all of the knowledge layer at once — and every hit reports which one it is.
list_topics is the fastest way to see the shape of what Graphium has worked out: a title and one-line summary per topic, the same "read the index first" approach Karpathy describes for an LLM-facing wiki. get_topic opens one topic and returns its body together with its sources — the sources the body cites for topics built from sources, or, for older topics built from claims, the claims it gathers and the notes each claim came from.
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, and to the PDF, Word file or web page they were imported from
- "What else was made from that source?" — starts from a source and finds the notes and topics that came from it
- "Save what we just worked out as a note titled …" — writes the conversation's outcome into your vault
- "Draw this procedure as a diagram." — returns the steps as a Mermaid flowchart (up to 60 steps)
- "Merge the duplicate topics." — finds duplicates, merges them, and records it so you can undo (quit Graphium first)
- "Read around page 3 of this PDF." — reads the source itself, not just what a topic says about it
- "Anything I still have to do this week?" — gathers the unchecked checklist items across your notes; the assistant reads any dates you wrote in the text and orders them for you
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.
A typical session
Here is what it looks like to consult your records while drafting a paper or writing analysis code in Claude Code:
- Get the overview — "What topics are in my notes?" (
list_topics) - Go deeper — "Tell me what you know about the synthesis conditions for Zn4Sb3" (
get_topic). You get the body and the names of the sources behind it - Check — "Show me the procedure, with conditions, for the runs that didn't come out single-phase" (
search_notes→get_note_steps). If something looks off, open the returned note id in Graphium - Write back — "Save what we just worked out as a note titled 'Re-sintering Zn4Sb3 tends to decompose it into ZnSb'" (
create_note). It appears in Graphium after a reload
A maintenance session looks different. Quit Graphium first, then:
- Look for problems — "Check my knowledge for duplicates" (
check_knowledge) - Merge — "Merge those two Zn4Sb3 topics" (
merge_topics). The assistant writes the combined body and the absorbed topic goes to the Trash - Confirm — "What did you just change?" (
list_operations) - Undo if it is wrong — "Undo that" (
undo_operation). Start Graphium again afterwards to see the result
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, topics and the other tools 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.
Connecting with Asterism Added in v0.95.0
Combined with Asterism (a knowledge graph product), Graphium's claims (judgments, rules, interpretations, observations) and topics become an Asterism knowledge graph. An AI can search Asterism to build an answer, then send the answer and its sources back to Graphium.
| Step | Who | What |
|---|---|---|
| 1. Set up (once) | You | Turn on "Connect with Asterism" under Settings → AI. Give your claims a type (judgment / rule / interpretation / sosa:Observation). Connect both the Graphium and Asterism MCP servers to Claude Desktop or similar |
| 2. First design (once) | You | Attach the JSON from export_asterism_claims to an Asterism chat, design the mapping, then approve and publish it (an example is in Asterism's docs/examples/graphium/) |
| 3. Regular sync | AI | export_asterism_claims (includeTopics: true, everything) → Asterism's resync_rows → mark_asterism_sent. Claims you edited or deleted arrive this way too |
| 4. Increments only | AI | export_asterism_claims (onlyUnsent: true) → Asterism's append_rows → mark_asterism_sent |
| 5. Search and send back | AI | Asterism's find_datasets → sparql_query (the source is source_url, a Graphium page) → Graphium's save_answer (claim ids in citations) |
source_urlis the URL of a page in this app (#knowledge/claim/<id>,#knowledge/topic/<id>). It becomes the source of Asterism's answer- In Asterism, topics are concepts (
skos:Concept) linked to claims. If material names and the like overlap with values in other datasets, Asterism suggests "links" - What has been sent is recorded in
appdata/asterism-sent.json - The type terms and the base IRI for claims can be changed under "Advanced settings" in Settings (recommended values are filled in)
What it deliberately does not do
It never edits your existing notes. create_note only adds new ones. save_answer only adds new Q&A pages — it does not touch your notes either, though the Q&A page it creates will be revised later by Graphium's own knowledge-layer maintenance, unlike a note. Nothing an assistant does through MCP can overwrite a note you wrote.
Knowledge pages can be maintained, and every change is recorded and undoable. Topics and Q&A pages can be rewritten, merged and archived (see above). Each of these is written to the Operations record with the client name, and you can undo it from Graphium. This is refused while Graphium is running, and no History-panel version is made — you go back through the Operations record. Claims the assistant makes are recorded and undone the same way.
The checks are mechanical only. check_knowledge finds orphaned and empty pages, duplicate titles, missing sources and contradiction marks. The AI-based checks (stale, gaps, semantic duplicates) are in Graphium's Upkeep view. The procedure diagram covers up to 60 steps; beyond that it shows the first 60 and a note.
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.
It does not manage tasks. list_todos reads the unchecked checklist items out of your notes; it cannot tick one off, add one, or give it a due date, an owner or a priority — Graphium keeps none of that. See your to-dos and task tools.
Notes and Q&A pages created through MCP appear after a reload. Both lists are built by the app, so something written while Graphium is open shows up the next time you reload or restart it. Changes made by upkeep tools show up the next time you start Graphium.
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.
The entry I added disappeared after restarting Claude Desktop. Editing the config file while the app is running lets the app overwrite it with its old copy. Quit the app completely with ⌘Q and edit the file again (see the warning in Setting it up).
The server does not start (the log shows spawn node ENOENT or similar). The desktop app cannot find node. Put the full path from which node in "command".
In Claude Code, it works in one folder but not another. It was registered without --scope user, so it only applies to the folder you registered it in. Register it again with claude mcp add --scope user ….
A tool from this page is missing, or the answers look out of date. The server file is still the one you built earlier. Rebuild it as described in Updating to a newer version.
A maintenance tool answers APP_RUNNING:. Graphium is running. Quit it completely and try again. The browser version can look as if it is still running for about 90 seconds after you close it.
A maintenance tool answers BUSY:. Another MCP client is writing right now. Wait a moment and try again.
A maintenance tool answers NO_INDEX:. The vault has no note-index.json yet, which means Graphium has never opened it. Start Graphium once, quit it, and try again.
Reading a PDF fails and says Node 20.16 or later is needed. Update Node.js to 20.16 or later (use the full path of that node in "command").
PDF and Word text do not work, but everything else does. The bundle was copied away from the clone. Run it from dist-mcp/ in the clone, or point your client at that path again.
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