Content
# Outline MCP Server
Servidor [Model Context Protocol](https://modelcontextprotocol.io/) para integrar [Outline](https://www.getoutline.com/) 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`:
```json
{
"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
```bash
npm install
npm run build
npm start
```
Para desarrollo:
```bash
npm run dev
```
Para recompilar automáticamente mientras editas:
```bash
npm run watch
```
## Configuración
El servidor lee la configuración desde variables de entorno:
```bash
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:
```bash
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
```json
{
"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:
```bash
npm run build
```
Luego apunta el cliente al archivo compilado:
```json
{
"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:
```json
"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`:
```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:
```text
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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```text
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.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available