# @synexiom-labs/nodiom-mcp

**MCP server for [nodiom](https://github.com/Synexiom-Labs/nodiom) — structured read/write access to Markdown documents for AI agents.**

[![npm version](https://img.shields.io/npm/v/@synexiom-labs%2Fnodiom-mcp)](https://www.npmjs.com/package/@synexiom-labs/nodiom-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

Expose nodiom's structural Markdown operations as [Model Context Protocol](https://modelcontextprotocol.io) 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](https://www.nodiom.md/?utm_source=github&utm_medium=nodiom-mcp-readme)**. 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

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

Or use directly with `npx` (no install required):

```bash
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`

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

### Claude Code

```bash
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):

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

### Any MCP client (stdio transport)

```json
{
  "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

| Package | Description |
|---|---|
| [`@synexiom-labs/nodiom`](https://github.com/Synexiom-Labs/nodiom) | The core library: use it directly in your Node.js code |
| `@synexiom-labs/nodiom-mcp` | This package: an MCP server for AI agents, on local Markdown files |
| [Nodiom Cloud](https://www.nodiom.md/?utm_source=github&utm_medium=nodiom-mcp-readme) | Hosted: shared documents and boards for agents and people across machines, with sign-in from Claude, ChatGPT, Cursor and VS Code |

---

## License

MIT — [Synexiom Labs Inc.](https://synexiomlabs.com)