Skip to main content
Glama
readeck-mcp
by alozur

Readeck MCP

Un servidor MCP que convierte una biblioteca de Readeck en una base de conocimiento de lectura/escritura para agentes de IA: los agentes pueden enviar el HTML que generan directamente a Readeck (auto-etiquetado por un LLM) y después recuperar y leer esos documentos. Construido con FastMCP — el mismo código se ejecuta como servidor local stdio o como servidor remoto HTTP detrás de un proxy inverso.

A diferencia de los MCP de Readeck existentes (que son asistentes de solo lectura), este ingiere HTML generado por agentes y lo auto-etiqueta con un LLM a partir de una taxonomía fija.

Herramientas

Herramienta

Propósito

readeck_save(html, title, labels?, url?, auto_label?)

Guardar HTML sin procesar como marcador legible; auto-etiqueta cuando no se dan etiquetas.

readeck_read(query, only_own?, max_results?, max_chars?)

Búsqueda: encontrar el/los documento(s) que mejor coinciden y devolver su texto legible completo.

readeck_search(query, limit?)

Buscar en la biblioteca (solo metadatos).

readeck_list_labels()

Listar las etiquetas existentes con recuentos.

readeck_save utiliza la API de creación JSON de Readeck con el campo html de HTML sin procesar (base64/data-URI no funcionan). Envía un User-Agent de navegador para que un WAF (p. ej. el error 1010 de Cloudflare) no lo bloquee, y hace un breve sondeo para devolver el id, word_count y reading_url del nuevo marcador.

Related MCP server: Sensefold MCP server

Auto-etiquetado

Cuando se llama a readeck_save sin labels, un LLM clasifica el documento. Es resistente a inyecciones por diseño: el modelo solo puede elegir entre una taxonomía fija (LABEL_TAXONOMY), y el resultado se cruza con esa lista en el lado del servidor, por lo que es imposible tener etiquetas fuera del vocabulario. Una etiqueta de origen (ORIGIN_LABEL, por defecto propio) siempre la añade el menú, nunca el LLM.

Independiente del proveedor (compatible con OpenAI o Anthropic). Funciona con planes gratuitos como Groq — para modelos de razonamiento como gpt-oss configura un LLM_MAX_TOKENS generoso y el servidor envía reasoning_effort: low automáticamente.

Salvaguardas

  • Autenticación HTTP de bloqueo ante fallos: mediante autorización de transporte HTTP, cada tool en invoca requiere Authorization: Bearer $MCP_AUTH_TOKEN (comparación de tiempo constante).

  • Validación de entradas: límite de tamaño de HTML, rechazo de no-HTML, lista de permitidos de esquemas de URL, saneamiento y comprobación de límites de etiquetas.

  • Limitación de ritmo tipo token-bucket por proceso.

  • Las llamadas LLM se reintentan en 429/5xx con retroceso y se degradan correctamente (el etiquetado es de mejor esfuerzo; un error nunca bloquea el guardado).

Configuración (entorno)

Variable

Por defecto

Notas

READECK_URL

http://localhost:8000

URL base de Readeck.

READECK_TOKEN

—

Requerido. Readeck → Ajustes → Tokens de API.

READECK_MCP_TRANSPORT

stdio

stdio o http.

READECK_MCP_HOST / READECK_MCP_PORT

0.0.0.0 / 8787

Solo modo http.

MCP_AUTH_TOKEN

—

Requerido en modo http (bloqueo ante autenticaciones).

AUTO_LABEL

true

Habilitar el auto-etiquetado por LLM.

ORIGIN_LABEL

propio

Etiqueta de origen siempre añadida.

LABEL_TAXONOMY

ver config.py

Vocabulario cerrado separado por comas.

MAX_AUTO_LABELS

3

Número máximo de temas LLM por documento.

LLM_PROVIDER

anthropic

anthropic o openai (compatible con OpenAI).

LLM_BASE_URL

https://api.anthropic.com

Incluye el prefijo de versión para openai (p. ej. .../v1).

LLM_MODEL

claude-haiku-4-5

Cualquier modelo de chat del proveedor elegido.

LLM_API_KEY

—

Clave para el proveedor de LLM.

LLM_MAX_TOKENS / LLM_TEXT_CHARS

2000 / 3000

Presupuesto de salida / texto de entrada enviado.

Local (stdio)

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

Regístrate con un cliente MCP (mcpServers), por ejemplo:

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

Remoto (HTTP / Docker)

Ejecútalo con READECK_MCP_TRANSPORT=http (ver Dockerfile). Colócalo detrás de tu proxy inverso o túnel, por ejemplo en https://mcp-readeck.example.com. Cuando se ejecute junto a Readeck, define READECK_URL=http://readeck:8000 para evitar el doble viaje público. Apunta los clientes al endpoint:

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

Nota: usa la ruta del endpoint sin barra final (/mcp, no /mcp/): algunos proxies convierten la redirección de la barra final en un 307 que rompe los clientes streamable-HTTP.

Define siempre un MCP_AUTH_TOKEN robusto antes de exponer el endpoint: ese token concede acceso de escritura a tu biblioteca.

Licencia

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents and coding assistants with advanced web crawling and RAG capabilities, allowing them to scrape websites and leverage that knowledge through various retrieval strategies.
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients like Claude, ChatGPT, and Cursor to search, read, and write back to one cross-model Markdown library of saved articles, videos, PDFs, notes, and conversations. Hosted remote server with OAuth 2.1 or Agent-key auth and read_only, edit, or full permission tiers.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read public web content as clean Markdown, search a private library of previously read documents, and access these tools via MCP, REST API, CLI, and WebMCP.
      23
      MIT