Outline MCP Server

Servidor Model Context Protocol para integrar Outline con clientes MCP. Permite que un asistente o agente compatible consulte, busque y gestione documentos de una instancia de Outline mediante su API.

Para Qué Sirve

Este servidor actúa como puente entre un cliente MCP y Outline. Una vez configurado, el cliente puede invocar herramientas para leer documentación interna, buscar contenido, crear notas, actualizar documentos y consultar colecciones.

Casos de uso típicos:

• Consultar la base de conocimiento de Outline desde un asistente de IA.
• Buscar documentación interna sin salir del cliente MCP.
• Crear o actualizar documentos en Markdown desde flujos automatizados.
• Usar Outline como memoria documental editable para agentes.

Características

• Lectura de documentos por ID.
• Búsqueda de texto en documentos de Outline.
• Listado de documentos, con filtro opcional por colección.
• Creación de documentos con contenido Markdown.
• Actualización de título, contenido y estado de publicación.
• Eliminación de documentos.
• Listado de colecciones.
• Consulta de información de una colección concreta.
• Transporte MCP por stdio por defecto, ideal para clientes locales.
• Transporte Streamable HTTP opcional para despliegues remotos.
• Modo solo lectura para ocultar herramientas de escritura.
• Timeout HTTP y reintentos acotados ante errores temporales de Outline.
• Validación de argumentos con esquemas Zod mediante el SDK MCP actual.

Requisitos

• Node.js >=18.
• Una instancia de Outline accesible por URL.
• Un token de API de Outline con permisos suficientes para las operaciones que quieras usar.

Instalación Rápida Con npx

La forma más sencilla es configurarlo directamente en tu cliente MCP usando npx:

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "getoutline-mcp-server"],
      "env": {
        "OUTLINE_BASE_URL": "https://tu-instancia-outline.com",
        "OUTLINE_API_KEY": "tu-token-de-api"
      }
    }
  }
}

Instalación Desde Código Fuente

npm install
npm run build
npm start

Para desarrollo:

npm run dev

Para recompilar automáticamente mientras editas:

npm run watch

Configuración

El servidor lee la configuración desde variables de entorno:

OUTLINE_BASE_URL=https://tu-instancia-outline.com
OUTLINE_API_KEY=tu-token-de-api
OUTLINE_READ_ONLY=false
MCP_TRANSPORT=stdio
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp
OUTLINE_MAX_RETRIES=2
OUTLINE_RETRY_BASE_DELAY_MS=100
# OUTLINE_HTTP_TIMEOUT_MS=10000

Puedes tomar env.example como referencia.

Variables disponibles:

Variable	Default	Descripción
OUTLINE_BASE_URL	requerido	URL base de tu instancia de Outline.
OUTLINE_API_KEY	requerido	Token de API de Outline. No se imprime en logs.
OUTLINE_READ_ONLY	false	Si es true, no registra outline_create_document, outline_update_document ni outline_delete_document.
MCP_TRANSPORT	stdio	Transporte MCP: stdio o http. Valores inválidos fallan al arrancar.
MCP_HTTP_HOST	127.0.0.1	Host de escucha para Streamable HTTP. Usa 0.0.0.0 solo si el despliegue lo protege correctamente.
MCP_HTTP_PORT	3000	Puerto HTTP cuando MCP_TRANSPORT=http.
MCP_HTTP_PATH	/mcp	Path HTTP del endpoint MCP. Debe empezar con /.
OUTLINE_MAX_RETRIES	2	Reintentos máximos por endpoint para 429, 5xx y errores transitorios de red. Usa 0 para desactivar.
OUTLINE_RETRY_BASE_DELAY_MS	100	Delay base para backoff acotado entre reintentos.
OUTLINE_HTTP_TIMEOUT_MS	sin valor	Timeout opcional en milisegundos para Axios.

Modo Solo Lectura

Con OUTLINE_READ_ONLY=true, el servidor no expone las herramientas de escritura en tools/list. Las herramientas ocultas son outline_create_document, outline_update_document y outline_delete_document.

Aunque actives este modo, usa también un token de Outline con permisos mínimos de lectura siempre que tu instancia lo permita.

Transporte Streamable HTTP

stdio sigue siendo el transporte por defecto y no requiere configurar variables HTTP. Para exponer el servidor por Streamable HTTP:

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp
npm start

El endpoint queda disponible en http://127.0.0.1:3000/mcp con transporte Streamable HTTP del SDK MCP. Si necesitas exponerlo fuera de la máquina local, cambia MCP_HTTP_HOST, por ejemplo a 0.0.0.0, y protege el acceso desde la red o un proxy.

Este cambio no agrega autenticación propia al endpoint HTTP. En producción, publícalo solo detrás de una red confiable, VPN, reverse proxy con autenticación, reglas de firewall o controles equivalentes.

Timeout Y Reintentos

El cliente de Outline puede reintentar errores temporales: 429, 500, 502, 503, 504, ECONNRESET, ETIMEDOUT y ECONNABORTED. No reintenta errores permanentes como 400, 401 o 403.

Configura OUTLINE_MAX_RETRIES=0 para desactivar reintentos. Define OUTLINE_HTTP_TIMEOUT_MS solo si quieres imponer un timeout explícito a las llamadas HTTP hacia Outline.

Cómo Obtener El Token De Outline

1. Entra en tu instancia de Outline.
2. Abre Settings.
3. Ve a API Tokens.
4. Crea un token nuevo.
5. Usa ese valor como OUTLINE_API_KEY.

Recomendación: crea un token con los permisos mínimos necesarios para tu caso de uso.

Configuración En Clientes MCP

Cliente Local Con npx

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "getoutline-mcp-server"],
      "env": {
        "OUTLINE_BASE_URL": "https://tu-instancia-outline.com",
        "OUTLINE_API_KEY": "tu-token-de-api"
      }
    }
  }
}

Cliente Local Desde Este Repositorio

Primero compila el proyecto:

npm run build

Luego apunta el cliente al archivo compilado:

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/ruta/absoluta/outline-mcp-server/dist/index.js"],
      "env": {
        "OUTLINE_BASE_URL": "https://tu-instancia-outline.com",
        "OUTLINE_API_KEY": "tu-token-de-api"
      }
    }
  }
}

En Windows, usa una ruta absoluta válida, por ejemplo:

"args": ["D:/work/outline-mcp-server/dist/index.js"]

OpenCode

OpenCode usa una forma de configuración distinta a otros clientes MCP: el comando va como un array único y las variables del proceso van en environment, no en env.

Ejemplo para C:\Users\gbaso\.config\opencode\opencode.json:

{
  "mcp": {
    "outline": {
      "type": "local",
      "command": [
        "node",
        "D:/work/outline-mcp-server/dist/index.js"
      ],
      "enabled": true,
      "environment": {
        "OUTLINE_BASE_URL": "https://tu-instancia-outline.com",
        "OUTLINE_API_KEY": "tu-token-de-api"
      }
    }
  }
}

Si usas env en OpenCode, el servidor puede arrancar sin OUTLINE_BASE_URL y OUTLINE_API_KEY, fallar al inicio y aparecer en logs como server unavailable key=outline type=local status=failed.

Los logs de OpenCode en Windows están en:

C:\Users\gbaso\.local\share\opencode\log\opencode.log

Después de modificar opencode.json, reinicia OpenCode. La configuración de MCP se carga al inicio y no se recarga en caliente.

Herramientas Disponibles

outline_get_document

Obtiene un documento por ID.

Parámetros:

• id: ID del documento.

Ejemplo:

{
  "name": "outline_get_document",
  "arguments": {
    "id": "document-id"
  }
}

outline_search_documents

Busca documentos en Outline.

Parámetros:

• query: texto de búsqueda.
• limit: número máximo de resultados. Por defecto 25, máximo 100.

Ejemplo:

{
  "name": "outline_search_documents",
  "arguments": {
    "query": "documentación del proyecto",
    "limit": 10
  }
}

outline_list_documents

Lista documentos, opcionalmente filtrados por colección.

Parámetros:

• collectionId: ID opcional de la colección.
• limit: número máximo de resultados. Por defecto 25, máximo 100.

outline_create_document

Crea un documento con contenido Markdown.

Parámetros:

• title: título del documento.
• text: contenido en Markdown.
• collectionId: ID opcional de la colección.
• parentDocumentId: ID opcional del documento padre.
• publish: si debe publicarse inmediatamente. Por defecto false.

Ejemplo:

{
  "name": "outline_create_document",
  "arguments": {
    "title": "Plan del proyecto",
    "text": "# Plan\n\nContenido inicial del documento.",
    "collectionId": "collection-id",
    "publish": true
  }
}

outline_update_document

Actualiza un documento existente.

Parámetros:

• id: ID del documento.
• title: nuevo título, opcional.
• text: nuevo contenido Markdown, opcional.
• publish: cambia el estado de publicación, opcional.

outline_delete_document

Elimina un documento por ID.

Parámetros:

• id: ID del documento.

outline_list_collections

Lista todas las colecciones disponibles.

No requiere parámetros.

outline_get_collection

Obtiene información de una colección por ID.

Parámetros:

• id: ID de la colección.

Desarrollo

Estructura principal:

src/
├── index.ts           # Servidor MCP y registro de herramientas
└── outline-client.ts  # Cliente HTTP para la API de Outline

Scripts disponibles:

• npm run build: compila TypeScript en dist/.
• npm test: ejecuta la suite Vitest sin credenciales reales de Outline.
• npm run test:coverage: ejecuta tests con cobertura global mínima del 85%.
• npm start: ejecuta dist/index.js.
• npm run dev: compila y ejecuta el servidor.
• npm run watch: recompila al detectar cambios.

Seguridad

• No incluyas OUTLINE_API_KEY en commits, logs ni documentación pública.
• Usa variables de entorno o el sistema de secretos de tu cliente MCP.
• Evita tokens con permisos excesivos si el cliente solo necesita lectura.
• Ten cuidado con herramientas de escritura o borrado: el servidor puede modificar tu instancia de Outline.
• Si usas MCP_TRANSPORT=http, protege el endpoint con controles externos; el servidor no implementa autenticación HTTP propia.

Limitaciones Actuales

• No implementa rate limiting interno; si haces muchas llamadas, depende de los límites de Outline.
• Las respuestas de Outline se devuelven como JSON de la API, con tipos TypeScript pragmáticos pero sin validación runtime exhaustiva de cada campo.
• El transporte HTTP es stateless; no agrega sesiones persistentes ni autenticación propia.

Licencia

MIT. Consulta LICENSE para más detalles.