@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, or any custom MCP client — can read, write, append, and delete content in Markdown files using structural selectors, without regex or string hacking.

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.

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 content of that section

nodiom_read_list

Read all list items under a section as a JSON array.

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.

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.