Rootr
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Open source Repository Open in the app JSON README (API)
About
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- inspirio-co
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.2.1
- Last push
- 2026-07-17T03:45:18Z
- Repository state
- ativo
- Language
- JavaScript
- License
- NOASSERTION
- Added
- 2026-08-29 04:00:11
- Updated
- 2026-08-29 04:00:11
- Origin id
io.github.inspirio-co/rootr-cli
README
# Rootr CLI + MCP Server
**Connect your team's living knowledge base to Claude, ChatGPT, and any AI agent.**
[Rootr](https://rootr.io) 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](https://rootr.io/en/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):
```bash
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.
```bash
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`**
| Env var | Config key | Description |
|---|---|---|
| `ROOTR_API_KEY` | `apiKey` | A `rootr_...` API key. Sent as the `x-api-key` header on every request. |
| `ROOTR_WORKSPACE` | `workspace` | Workspace id |
| `ROOTR_BASE_URL` | `baseUrl` | Defaults to `https://rootr.io/api/v1` |
Save to the config file (created with `chmod 600`):
```bash
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**.
```bash
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:
| Group | Tools (examples) |
|---|---|
| **Documents** | `rootr_list`, `rootr_read`, `rootr_append` *(recommended, conflict-free)*, `rootr_edit`, `rootr_write`, `rootr_search`, `rootr_document_versions`, `rootr_delete_node`, `rootr_duplicate_node` |
| **Publishing & comments** | `rootr_publish_document`, `rootr_set_document_public`, `rootr_document_public_status`, `rootr_comment_document`, `rootr_list_document_comments` |
| **Workspaces & scaffolding** | `rootr_workspaces`, `rootr_scaffold_plan`, `rootr_create_workspace`, `rootr_scaffold_apply` |
| **Databases** (typed columns + board/table views) | `rootr_read_database`, `rootr_add_row`, `rootr_update_row`, `rootr_delete_row`, `rootr_list_rows` |
| **Spreadsheets** (formulas) | `rootr_create_spreadsheet`, `rootr_read_spreadsheet`, `rootr_update_spreadsheet`, `rootr_create_sheet`, `rootr_update_sheet`, `rootr_delete_sheet`, `rootr_patch_spreadsheet_cells` |
| **Whiteboards** | `rootr_create_whiteboard`, `rootr_read_whiteboard`, `rootr_update_whiteboard` |
| **Forms** | `rootr_create_form`, `rootr_read_form`, `rootr_update_form`, `rootr_list_form_responses`, `rootr_submit_form_response`, `rootr_create_form_share_link`, `rootr_list_form_share_links` |
| **CRM** | `rootr_crm_*` — companies, contacts, deals (kanban), activities, tasks, CSV import |
| **Presentations** | `rootr_create_presentation`, `rootr_read_presentation`, `rootr_update_presentation`, `rootr_update_presentation_slide`, `rootr_append_presentation_slides`, `rootr_reorder_presentation_slides` |
| **LOG datastores** | `rootr_create_log_store`, `rootr_update_log_fields`, `rootr_add_log_entries`, `rootr_query_log_entries`, `rootr_log_stats` |
| **Issues** | `rootr_create_issue_tracker`, `rootr_list_issues`, `rootr_create_issue`, `rootr_get_issue`, `rootr_update_issue`, `rootr_comment_issue` |
| **Webhooks** | `rootr_list_webhooks`, `rootr_create_webhook`, `rootr_delete_webhook` |
| **GraphRAG ask** | `rootr_ask` — natural-language root-cause Q&A over the knowledge graph, with citations |
| **Images** | `rootr_generate_image`, `rootr_remove_image_background` |
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:
```json
{
"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](https://inspirio.co) · [rootr.io](https://rootr.io) · info@inspirio.co