marginalia

Turn any Markdown into a browser-based, click-to-comment thread over MCP. Comments record as clean, anchored MCP tool_results; replies render as in-page, re-annotatable cards. One portable FastMCP-over-stdio server, launched with uvx, installs identically across Claude Code, Cline, and opencode.

See USAGE.md for the tool loop and environment variables.

Install

marginalia runs via uvx straight from git — no clone, no PyPI release needed. The snippets below pin the latest release tag, @v2.1.0. To track unreleased changes instead, swap the tag for @main.

Warm the cache once: the first uvx --from git+… resolve can take long enough that a client drops the server on first launch. Run the bare command once in a terminal to populate the uvx cache, then start your client. marginalia is a stdio MCP server (no --help), so redirect stdin from /dev/null to make it exit immediately once the cache is warm:

uvx --from git+https://github.com/Jin-HoMLee/marginalia@v2.1.0 marginalia </dev/null

Claude Code

claude mcp add --scope user marginalia -- uvx --from git+https://github.com/Jin-HoMLee/marginalia@v2.1.0 marginalia

Optional (for CC's lazy-loaded skill UX): copy USAGE.md to ~/.claude/skills/marginalia/SKILL.md and prepend a two-line frontmatter (name: marginalia / description: …). The repo ships no maintained SKILL.md.

Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "marginalia": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Jin-HoMLee/marginalia@v2.1.0", "marginalia"],
      "env": { "MARGINALIA_POLL_S": "540" },
      "timeout": 3600
    }
  }
}

MARGINALIA_POLL_S is optional here — 540 is already the default, so the env block can be dropped entirely. It's shown only to make the long-poll window explicit.

If Cline is launched from the VS Code GUI and can't find uvx on PATH, use the absolute path to uvx (e.g. ~/.local/bin/uvx) as command.

opencode (opencode.json)

{
  "mcp": {
    "marginalia": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/Jin-HoMLee/marginalia@v2.1.0", "marginalia"],
      "environment": { "MARGINALIA_POLL_S": "20" },
      "enabled": true
    }
  }
}

MARGINALIA_POLL_S=20 is required — opencode caps MCP tool execution at ~30s, so the default 540s long-poll would be killed.

Develop

git clone https://github.com/Jin-HoMLee/marginalia && cd marginalia
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest          # 44 tests

License

MIT — see LICENSE.