outline-mcp

Servidor MCP de solo lectura para Outline. Da a un agente acceso de búsqueda y lectura a tu wiki — sin escrituras, por diseño.

Por qué

La API de Outline es una superficie RPC plana — cada endpoint es POST {base}/api/<method> con un cuerpo JSON y un token Bearer. Esa uniformidad significa que un servidor MCP útil es una única función de solicitud más una lista de herramientas seleccionadas. Este paquete es deliberadamente pequeño: sin dependencias de ejecución más allá del SDK de MCP y zod, y control total sobre las descripciones de herramientas y la forma de salida que determinan si el agente elige la herramienta correcta.

El servidor es de solo lectura: no hay ninguna ruta de creación, actualización, movimiento o archivo en el código.

Related MCP server: outline-mcp

Herramientas

get_document acepta una URL completa, un urlId simple o un UUID. Un urlId es [A-Za-z0-9]{10,15} — un slug sin un sufijo de id válido se rechaza localmente, porque la API responde 400 validation_error para ello.

Requisitos

• Node 18 o superior (usa fetch integrado; sin dependencias nativas).

• Una instancia de Outline — autoalojada o Outline.com.

Primeros pasos

git clone https://github.com/minhquan2904/outline-mcp.git
cd outline-mcp
npm ci

Obtén una clave de API

En Outline: Configuración → API y aplicaciones → Nueva clave de API. El valor comienza con ol_api_ seguido de 38 caracteres alfanuméricos.

Configura las dos variables de entorno

export OUTLINE_API_URL=https://your-outline-instance
export OUTLINE_API_KEY=ol_api_…
node index.js

Configuración

El servidor lee exactamente dos variables de entorno:

Claude Code — mcp.json (proyecto) o .mcp.json (usuario):

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Nota: Claude Desktop no expande las referencias ${VAR} en este archivo — pega la clave literalmente, no escribas "${OUTLINE_API_KEY}".

Cualquier otro cliente MCP (Zed, Cline o cualquier cosa que hable el protocolo MCP stdio) — misma forma: lanza node /path/to/outline-mcp/index.js con las dos variables en su entorno.

Cómo funciona

flowchart LR
    CC[Claude Code / any MCP client]
    OM[outline-mcp<br/>Node 18+, stdio server]
    O[Outline instance]
    F[format.js<br/>parse ref · truncate · render]
    C[client.js<br/>timeout · error map · 429 retry]

    CC -->|stdio| OM
    OM -->|"POST /api/{method} · Bearer ol_api_…"| O
    OM -.-> F
    OM -.-> C

El servidor nunca valida credenciales al inicio. Un servidor que sale al arrancar aparece en el cliente como "no se pudo conectar" sin explicación; en cambio, se inicia, lista sus herramientas y cada llamada devuelve un mensaje que nombra la variable que falta.

Desarrollo

npm ci
npm test          # unit tests, fully offline (fetch is stubbed)
npm run smoke     # every tool against a real instance; no-ops without credentials

npm run smoke requiere OUTLINE_API_URL + OUTLINE_API_KEY apuntando a una instancia en vivo; sin ellos imprime una línea "smoke omitido" y sale con 0. Consulta CONTRIBUTING.md para saber cómo añadir una herramienta.

Limitaciones

• Solo lectura por diseño. Sin escrituras de creación, actualización, movimiento, archivo o comentarios.

• Los adjuntos no se resuelven. Las imágenes y archivos incrustados permanecen como enlaces /api/attachments.redirect?id=… en el markdown; no se cargarán para un agente que lea el texto.

• Sin señal proactiva de límite de velocidad. La instancia no devuelve cabeceras RateLimit-*. En un 429 el cliente respeta Retry-After (máximo 10 s) y reintenta exactamente una vez, luego informa del fallo.

• Los documentos largos se truncan en maxChars (por defecto 40 000) con un marcador que indica la longitud total real.

Seguridad

La clave de API viaja solo en la cabecera Authorization de las solicitudes salientes. Cualquier mensaje de error que salga del cliente pasa por un paso de redacción que reemplaza la clave con ol_api_***, y nada en la ruta de la clave (el transporte stdio o el registro de stderr) imprime la clave en sí. Si tu instancia de Outline admite claves con ámbito, prefiere una clave con ámbito de solo lectura para este servidor.

Licencia

MIT — consulta LICENSE para el texto completo.