Nodiom MCP README

@synexiom-labs/nodiom-mcp

MCP server for nodiom — structured read/write access to Markdown documents for AI agents.

Expose nodiom's structural Markdown operations as Model Context Protocol tools. Any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, or your own client) can read, write, append and delete content in Markdown files using structural selectors, without regex or string hacking.

Local files or shared state? This server works on Markdown files on your machine, for agents running there. When agents on different machines, from different vendors, or your teammates need the same documents, use Nodiom Cloud. It's the same engine, hosted, with shared boards, a human review step and attribution. Connect from Claude, ChatGPT, Cursor or VS Code by adding https://api.nodiom.md/mcp and signing in.

Install

npm install -g @synexiom-labs/nodiom-mcp

Or use directly with npx (no install required):

npx @synexiom-labs/nodiom-mcp

Setup

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nodiom": {
      "command": "npx",
      "args": ["-y", "@synexiom-labs/nodiom-mcp"]
    }
  }
}

Claude Code

claude mcp add -s user nodiom -- npx -y @synexiom-labs/nodiom-mcp

The -s user flag registers the server globally across all your projects. Without it, the server is only active when Claude Code's working directory matches the project where you ran the command.

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "nodiom": {
      "command": "npx",
      "args": ["-y", "@synexiom-labs/nodiom-mcp"]
    }
  }
}

Any MCP client (stdio transport)

{
  "command": "npx",
  "args": ["-y", "@synexiom-labs/nodiom-mcp"]
}

Tools

The server exposes 7 tools, all operating on local Markdown files by absolute path.

nodiom_tree

Get the structural outline of a document before reading or modifying it.

file: "/path/to/wiki.md"
→ Returns a nested JSON tree of all headings

nodiom_read

Read the content at a structural location.

file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks > ### Active"
→ Returns the Markdown body of that section (the heading line itself isn't included)

nodiom_read_list

Read all list items under a section as a JSON array: each item's source, marker and nested lines included.

file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Team"
→ ["- Alice Chen — Tech Lead", "- Bob Martinez — ML Engineer", ...]

nodiom_write

Replace the content of a section (heading is preserved).

file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Overview"
content: "Project Aurora is on track for Q3 delivery."
→ Replaces only the Overview body. Nothing else changes.

Pointed at one list item (## Tasks > li[contains="staging"]), it replaces just that item. Text written without its own bullet keeps the item's marker and checkbox.

nodiom_append

Append content after the last item in a section.

file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks > ### Active"
content: "- [ ] Deploy to staging"
→ Adds the new task at the end of Active. Existing tasks untouched.

nodiom_delete

Remove a node or section.

file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks > ### Completed > li[0]"
→ Removes the first completed task.

nodiom_query

Check if a section exists and get its metadata.

file: "/path/to/wiki.md"
selector: "# Project Aurora > ## Tasks"
→ { "exists": true, "type": "heading", "depth": 2, "childCount": 3, "index": 4 }

Selector Syntax

Selectors are " > "-separated paths of heading and element segments:

"# Project"                          → H1 section
"# Project > ## Tasks"               → H2 under H1
"# Project > ## Tasks > ### Active"  → H3 under H2 under H1
"## Tasks > li[0]"                   → First list item
"## Tasks > li[-1]"                  → Last list item
"## Notes > p[0]"                    → First paragraph
"## Arch > table[0]"                 → First table
"## Tasks > li[contains=\"auth\"]"    → The list item containing "auth"
"## Notes[1]"                        → The second "## Notes", when the heading repeats

A content selector (li[contains="…"]) must match exactly one item, and keeps pointing at the same item when others are added or removed — prefer it whenever more than one writer touches a file. A heading that appears more than once must be addressed with an index (## Notes[0], ## Notes[1]); the error lists the options. YAML or TOML frontmatter is preserved and never treated as a heading.

When a selector doesn't match, the error includes fuzzy suggestions: "Did you mean '## Tasks'?"

Example Agent Prompt

Once the server is configured, you can instruct Claude naturally:

"Look at my project wiki at /Users/me/projects/aurora/wiki.md. What are the active tasks? Add a new task: 'Write integration tests'. Then move the first completed task to a new '## Archive' section."

Claude will use nodiom_tree to understand the structure, nodiom_read_list to get the tasks, nodiom_append to add the new one, and nodiom_read + nodiom_delete + nodiom_append to move the completed task — all without loading the entire file as a string.

Part of the Nodiom ecosystem

License

MIT — Synexiom Labs Inc.