Rootr CLI + MCP Server

Connect your team's living knowledge base to Claude, ChatGPT, and any AI agent.

Rootr is a team knowledge & document workspace. This package is the official way to give an AI agent direct, permissioned access to your team's shared documents, structured data, and institutional knowledge — so your assistant already knows what your team knows, instead of you copy-pasting context into every conversation.

There are two ways to connect.

1. Remote connector — no install (recommended)

Rootr hosts a remote MCP endpoint over Streamable HTTP. In Claude Desktop, claude.ai, or ChatGPT, add a connector with just the URL and sign in with OAuth:

https://rootr.io/mcp

No JSON, no CLI, no tokens to paste. Log in, pick the workspace, and your team's docs are available to the assistant with your existing permissions. See the docs.

2. Local CLI / stdio MCP server (rootr-cli)

For the shell, or for agents that speak to a local stdio MCP server (e.g. Claude Code):

npm install -g rootr-cli
rootr config --api-key rootr_xxxx --workspace ws_xxx
rootr mcp          # start the stdio MCP server

The rootr command also works standalone: ls, read, write, append, edit, search, ask, ws, config.

Pure Node.js ESM, no build step. Requires Node 18+ (uses the built-in fetch).

• Homepage: https://rootr.io
• Docs: https://rootr.io/en/docs
• npm: https://www.npmjs.com/package/rootr-cli

Install

Run it straight from a clone, or install globally.

npm install -g rootr-cli
rootr --help

# or from source
cd cli && npm install
node bin/rootr.js --help

Configuration

Precedence: environment variables > ~/.rootr/config.json

Save to the config file (created with chmod 600):

rootr config --api-key rootr_xxxxxxxxxxxxxxxx --workspace ws_123
# optional on-prem / dev base URL
rootr config --api-key rootr_xxx --workspace ws_123 --base-url https://dev.rootr.io/api/v1

rootr config          # show current config (api key shown masked)

Two kinds of key

Rootr API keys come in two kinds, and some tools require a specific one:

• Workspace key — scoped to a single workspace (docs:read / docs:write / graph:read / ask / webhooks:manage). Enough for most document, LOG, issue, webhook, and ask tools.
• Account key (PAT) — acts across your whole account. With the workspaces:create scope it can create new workspaces (rootr_create_workspace). Using a workspace key for an account-level action returns a 403 with a hint that an account key is required.

CLI usage

Path rule: an argument starting with / is treated as a path (resolved to a node id via the by-path API; needs a workspace set). Otherwise it is treated as a node id.

rootr ls                                   # whole tree  (TYPE<TAB>path)
rootr ls /notes                            # subtree

rootr read /notes/todo.md                  # markdown to stdout
rootr read /notes/todo.md --json           # full JSON incl. metadata

echo "# Title" | rootr write /notes/new.md # full replace (creates if missing)
rootr write /notes/new.md --file ./local.md

rootr append /notes/log.md "Deployed today"          # safe, conflict-free
rootr append /notes/log.md "- one more" --heading "## Todo"

rootr edit /notes/todo.md --find "- [ ] ship" --replace "- [x] ship"

rootr search "deploy runbook"              # path — snippet
rootr ws                                   # list workspaces (id<TAB>name)
rootr ask "why did latency go up after last week's deploy?"

append never rewrites the whole document, so it is safe to run concurrently. write supports --if-match "\"etag\"" for optimistic concurrency (a 412 means the document changed underneath you — re-read and retry). edit returns 409 if --find is missing or not unique; pass --all to replace every match. ask queries the workspace knowledge graph (GraphRAG) and prints the answer plus citations (document path: quote).

Use as an MCP server

rootr mcp starts a Model Context Protocol server over stdio. It exposes 80+ tools across the full Rootr surface, so an agent can author and query every node type:

Tool descriptions steer agents to prefer rootr_append / rootr_edit over the destructive rootr_write. Tools that take a workspace argument fall back to ROOTR_WORKSPACE (or the config default) when it is omitted. All tool schemas are in English; JSON-returning tools respond with pretty-printed JSON text.

Register in Claude Code / Claude Desktop

Add to ~/.claude.json (Claude Code) or your Claude Desktop MCP config:

{
  "mcpServers": {
    "rootr": {
      "command": "rootr",
      "args": ["mcp"],
      "env": {
        "ROOTR_API_KEY": "rootr_xxxxxxxxxxxxxxxx",
        "ROOTR_WORKSPACE": "ws_123"
      }
    }
  }
}

(If you did not install globally, use "command": "node" and "args": ["/path/to/rootr-cli/bin/rootr.js", "mcp"].)

Error handling

On a non-2xx response the CLI prints the API message (when present) to stderr and exits 1:

• 401 / 403 — check the API key / workspace scope
• 412 — document changed since you read it (If-Match mismatch): re-read and retry
• 409 — the server's reason is shown verbatim (e.g. edit find not found / not unique)

Layout

• bin/rootr.js — entry point, command dispatch
• lib/config.js — config load/save
• lib/client.js — Rootr REST API client
• lib/resolve.js — shared path/id target resolution
• lib/mcp.js — MCP stdio server, assembles all tool groups
• lib/mcp-tools/* — one module per tool group (documents, workspaces, databases, spreadsheets, whiteboards, forms, crm, presentations, logs, issues, webhooks, ask, misc)

Dependencies: @modelcontextprotocol/sdk (MCP server) and zod (tool input schemas). The CLI core has no external dependencies. No build step — pure ESM JavaScript.

Made by Inspirio · rootr.io · info@inspirio.co