@oranger-md/mcp

Model Context Protocol server for Oranger Markdown. Lets AI agents — Claude Code, Claude Desktop, Cursor, Cline, Continue, anything that speaks MCP — read, write, version, and comment on Oranger documents through the same HTTP API humans use from the web app.

The author of every edit made through this server is you (the user the API token belongs to). The Oranger timeline shows "Alice (via Claude Desktop)" so collaborators can see which edits came from an agent.

Status

Pre-release. The Oranger HTTP API is stable; this package wraps it. Expect the tool surface to grow.

Tools

| Tool | What it does | | ----------------- | --------------------------------------------------------- | | whoami | Confirm the token is wired up; returns your user info. | | list_spaces | List spaces you have any role on. | | get_tree | Walk the file + folder tree in a space. | | get_file | Read a file (metadata + markdown body). | | create_file | Create a markdown file (optionally with body). | | update_file | Edit body (body or edits) and/or rename/move/pin. Concurrent edits to different parts of a doc auto-merge in edits mode. | | list_versions | History of a file, newest first. | | restore_version | Restore a prior version as the new current (non-destructive). | | list_threads | List comment threads on a file (comments included inline). | | get_thread | Read one comment thread by id. | | comment_on_file | Start a comment thread, optionally anchored to lines. |

Install — one line

Mint an API token at https://oranger.md/settings/tokens (or via the API), then:

Claude Code

claude mcp add oranger -s user -e ORANGER_API_TOKEN=org_v1_… -- npx -y @oranger-md/mcp

Stored in ~/.claude.json (your machine, never committed). Done.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "oranger": {
      "command": "npx",
      "args": ["-y", "@oranger-md/mcp"],
      "env": {
        "ORANGER_API_TOKEN": "org_v1_…"
      }
    }
  }
}

Restart Claude Desktop. The Oranger tools appear under the tools menu.

Cursor / Cline / Continue

Drop the same JSON into the client's mcp.json:

{
  "mcpServers": {
    "oranger": {
      "command": "npx",
      "args": ["-y", "@oranger-md/mcp"],
      "env": {
        "ORANGER_API_TOKEN": "org_v1_…"
      }
    }
  }
}

Shared .mcp.json in a repo

If you're checking the config in for a team, don't embed the secret — use shell expansion so the token stays in each developer's env:

{
  "mcpServers": {
    "oranger": {
      "command": "npx",
      "args": ["-y", "@oranger-md/mcp"],
      "env": {
        "ORANGER_API_TOKEN": "${ORANGER_API_TOKEN}"
      }
    }
  }
}

Each developer exports ORANGER_API_TOKEN from their shell (.zshrc, direnv, 1Password CLI, etc.) using their own token.

Get an API token

1. Sign in to Oranger.
2. Open Settings → API tokens (or PUT /api/me/tokens/{uuid} via curl — see docs/api-tokens.md).
3. Name the token after the client you're wiring up (e.g. "Claude Desktop"), pick its icon, create.
4. Copy the org_v1_… secret once — it isn't shown again. The reveal panel shows ready-to-paste install snippets with the secret inlined.

Local dev against your own Oranger instance

Set ORANGER_API_BASE=http://localhost:3000 and use a token minted against your local Postgres. See docs/api-tokens.md.

claude mcp add oranger -s user \
  -e ORANGER_API_BASE=http://localhost:3000 \
  -e ORANGER_API_TOKEN=org_v1_… \
  -- npx -y @oranger-md/mcp

Configuration

| Variable | Required | Default | Notes | | -------------------- | -------- | --------------------- | --------------------------------------- | | ORANGER_API_TOKEN | yes | — | org_v1_… API token. | | ORANGER_API_BASE | no | https://oranger.md | Override for self-hosted or local dev. |

Security notes

• Tokens are scoped to your user. Revoke via DELETE /api/me/tokens/{id} (or the Settings UI) the moment you suspect a leak.
• Tokens cannot be used to mint other tokens. Add new clients by signing in to Oranger directly.
• Edits made through the token are attributed to you. The version timeline records via_token = { token_id, name, client_type } so you can tell which client wrote what.
• The Claude Code 1-liner writes to ~/.claude.json (your home directory) and is never committed. Project-scoped .mcp.json files are often committed — use the ${ORANGER_API_TOKEN} shell-expansion form there.

Develop the server itself

git clone https://github.com/your-org/oranger-markdown.git
cd oranger-markdown/mcp
npm install
npm run dev          # tsx watch mode
npm run build        # compile to dist/

To test a local build inside Claude Code without publishing:

npm run build
claude mcp add oranger-dev -e ORANGER_API_TOKEN=org_v1_… \
  -- node /absolute/path/to/mcp/dist/index.js

License

MIT.