Readeck MCP

An MCP server that turns a Readeck library into a read/write knowledge base for AI agents: agents can push the HTML they generate straight into Readeck (auto-tagged by an LLM) and later retrieve and read those documents back. Built with FastMCP — the same code runs as a local stdio server or a remote HTTP server behind a reverse proxy.

Unlike existing Readeck MCPs (which are read-only reading assistants), this one ingests agent-generated HTML and auto-labels it with an LLM from a fixed taxonomy.

Tools

readeck_save uses Readeck's JSON create API with the raw-HTML html field (base64/data-URI do not work). It sends a browser User-Agent so a WAF (e.g. Cloudflare error 1010) doesn't block it, and polls briefly to return the new bookmark id, word_count and reading_url.

Related MCP server: Doc Monitor MCP

Auto-labeling

When you call readeck_save without labels, an LLM classifies the document. It's injection-resistant by design: the model may only pick from a fixed taxonomy (LABEL_TAXONOMY), and the result is intersected with that list server-side, so out-of-vocabulary labels are impossible. An origin label (ORIGIN_LABEL, default propio) is always added by code, never the LLM.

Provider-agnostic (OpenAI-compatible or Anthropic). Works with free tiers such as Groq — for reasoning models like gpt-oss set a generous LLM_MAX_TOKENS and the server sends reasoning_effort: low automatically.

Guardrails

• Fail-closed HTTP auth: over HTTP transport every tool call requires Authorization: Bearer $MCP_AUTH_TOKEN (constant-time compare).

• Input validation: HTML size cap, non-HTML rejection, URL-scheme allowlist, label sanitization + cap.

• Token-bucket rate limiting per process.

• LLM calls retry on 429/5xx with backoff and degrade gracefully (labeling is best-effort; a failure never blocks the save).

Configuration (environment)

Local (stdio)

READECK_TOKEN=... uv run --script server.py --selftest   # smoke test

Register with an MCP client (mcpServers), e.g.:

{
  "mcpServers": {
    "readeck": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/readeck-mcp/server.py"],
      "env": { "READECK_URL": "https://readeck.example.com", "READECK_TOKEN": "..." }
    }
  }
}

Remote (HTTP / Docker)

Run with READECK_MCP_TRANSPORT=http (see Dockerfile). Put it behind your reverse proxy / tunnel at e.g. https://mcp-readeck.example.com. When co-located with Readeck, set READECK_URL=http://readeck:8000 to skip the public round-trip. Point clients at the endpoint:

{
  "mcpServers": {
    "readeck": {
      "type": "http",
      "url": "https://mcp-readeck.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Note: use the endpoint path without a trailing slash (/mcp, not /mcp/) — some proxies turn the trailing-slash redirect into a 307 that breaks streamable-HTTP clients.

Always set a strong MCP_AUTH_TOKEN before exposing the endpoint — the token grants write access to your library.

License

MIT