Agama — Redmine MCP Server

Servidor MCP para Redmine. Permite que agentes de IA trabajen con incidencias mediante comandos simples en lenguaje natural. Funciona igual de bien como herramienta personal para un desarrollador individual, o desplegado una vez y compartido por todo el equipo.

GitHub

Documentación

🦎 Agama — Redmine MCP Server

Servidor MCP para Redmine. Permite que los agentes de IA trabajen con incidencias usando comandos sencillos en lenguaje natural.

Funciona igual de bien como herramienta personal para un desarrollador individual, o desplegado una vez y compartido por todo el equipo.

┌──────────┐   MCP (stdio)   ┌─────────────────────┐   REST/JSON   ┌──────────┐
│  Agent   │ ──────────────▶ │  Redmine MCP Server │ ────────────▶ │ Redmine  │
│ (client) │ ◀────────────── │   (this project)    │ ◀──────────── │  server  │
└──────────┘   tool results  └─────────────────────┘     HTTP      └──────────┘

💬 Solo pregunta

"¿Qué incidencias están asignadas a mí? Ordénalas por prioridad."

"Crea un error en el proyecto Web: el botón de inicio de sesión no responde en móvil, márcalo como urgente."

"Resume la incidencia #456 y todas sus subtareas."

"¿Cuántas horas registré esta semana, desglosadas por proyecto?"

Requisitos

Node.js 22+
Una instancia de Redmine con la API REST habilitada (Administración → Ajustes → API)
Una clave API de Redmine: ve a Mi cuenta → Clave de acceso API mientras estás conectado

Inicio rápido

La mayoría de los clientes MCP (por ejemplo, Claude Desktop) lanzan el servidor por ti: configúralo una vez y olvídate:

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "@0xkillaflow/agama-redmine-mcp"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your-redmine-api-key"
      }
    }
  }
}

Para Claude Desktop, esto va en claude_desktop_config.json (Ajustes → Desarrollador → Editar Configuración). Reinicia el cliente y las herramientas de Redmine aparecerán en su lista de herramientas.

Para ejecutarlo de forma independiente desde una terminal, en su lugar:

REDMINE_URL=https://redmine.example.com REDMINE_API_KEY=your-redmine-api-key \
  npx -y @0xkillaflow/agama-redmine-mcp

El servidor habla MCP sobre stdio y registra en stderr, de modo que stdout permanece limpio para el protocolo.

Configuración

Se establece mediante variables de entorno, validadas al inicio. Consulta .env.example para una plantilla.

Variable	Obligatoria	Predeterminado	Propósito
`REDMINE_URL`	sí	—	URL base de la instancia de Redmine
`REDMINE_API_KEY`	sí	—	Clave API para el usuario que actúa
`REDMINE_TIMEOUT_MS`	no	`30000`	Tiempo de espera por solicitud en milisegundos
`REDMINE_ALLOWED_DIRECTORIES`	no	vacío	Directorios que las herramientas de adjuntos pueden usar
`LOG_LEVEL`	no	`info`	`debug` \| `info` \| `warn` \| `error`
`MCP_TRANSPORT`	no	`stdio`	`stdio` (único modo soportado hoy)

Acceso a archivos (`REDMINE_ALLOWED_DIRECTORIES`)

Las herramientas de adjuntos son las únicas que tocan tu sistema de archivos, y solo pueden hacerlo dentro de esta lista de permitidos: una lista separada por : de directorios absolutos (; en Windows). Gobierna ambas direcciones: lecturas para redmine_upload_attachment y escrituras para redmine_download_attachment.

REDMINE_ALLOWED_DIRECTORIES=/Users/you/redmine-files:/tmp/redmine-downloads

Por defecto está vacía, lo que significa que no hay acceso local a archivos en absoluto — ambas herramientas rechazan cualquier ruta hasta que te suscribas. Ese valor predeterminado es deliberado: un agente que se puede convencer para subir un archivo es un agente al que se puede convencer para subir ~/.ssh/id_rsa o el .env que contiene tu clave API. Permite el directorio más estrecho que haga el trabajo. Las rutas se resuelven completamente (segmentos .. y enlaces simbólicos incluidos) antes de la comprobación, de modo que un enlace simbólico dentro de un directorio permitido no puede apuntar fuera de él, y las descargas nunca sobrescriben un archivo existente.

Herramientas

Diecinueve herramientas orientadas a intención, cada una etiquetada con anotaciones de seguridad MCP. Referencia completa: docs/tools.md.

Herramienta	Tipo	Descripción
`redmine_list_issues`	lectura	Buscar/filtrar incidencias por estado, asignado, tracker, fechas…
`redmine_get_issue`	lectura	Detalle completo de la incidencia, opcionalmente con diarios y adjuntos
`redmine_create_issue`	escritura	Crear una incidencia
`redmine_update_issue`	escritura	Editar el estado, asignado, notas… de una incidencia
`redmine_delete_issue`	escritura · destructivo	Eliminar permanentemente una incidencia: sin deshacer, en cascada
`redmine_manage_issue_watchers`	escritura	Añadir/quitar un observador (suscripción de notificaciones)
`redmine_list_issue_relations`	lectura	Enlaces de dependencia de una incidencia, o una relación por su id
`redmine_create_issue_relation`	escritura	Vincular dos incidencias (bloquea, precede, duplica, relaciona…)
`redmine_delete_issue_relation`	escritura · destructivo	Eliminar un enlace: de alcance limitado y reversible
`redmine_search`	lectura	Búsqueda de texto libre en incidencias, wiki, noticias, proyectos
`redmine_list_projects`	lectura	Listar proyectos visibles
`redmine_get_project`	lectura	Detalle completo del proyecto, trackers/categorías/actividades
`redmine_list_time_entries`	lectura	Consultar tiempo registrado
`redmine_create_time_entry`	escritura	Registrar horas contra una incidencia o proyecto
`redmine_get_current_user`	lectura	"Quién soy": el usuario de la clave API, membresías, grupos
`redmine_list_users`	lectura	Encontrar usuarios por nombre/estado/grupo — con control de administrador en la mayoría de los sitios
`redmine_list_reference_data`	lectura	Estados, trackers, prioridades, actividades, categorías de documentos
`redmine_upload_attachment`	escritura	Subir un archivo local → token para el array `uploads` de una incidencia
`redmine_download_attachment`	escritura	Guardar un adjunto en un directorio local (escribe en el disco)

Aviso: redmine_delete_issue es la herramienta que destruye datos: Redmine no tiene papelera y el borrado se lleva los comentarios, entradas de tiempo, adjuntos y relaciones de la incidencia. Está anotada como destructiveHint: true para que un cliente MCP pueda requerir confirmación; si tu cliente no se basa en eso, trata cada llamada como definitiva. redmine_delete_issue_relation lleva la misma anotación pero es mucho más limitada: elimina un solo enlace entre dos incidencias, y redmine_create_issue_relation lo restablece en una sola llamada.

Aviso: al escribir, Redmine ignora silenciosamente un tracker_id, status_id o fixed_version_id desconocido en lugar de dar error: comprueba siempre la incidencia devuelta. Lo mismo se aplica a is_private, que se descarta silenciosamente si tu rol carece del permiso "establecer público/privado".

Seguridad

El servidor se ejecuta localmente y actúa como un solo usuario: tu REDMINE_API_KEY nunca sale de tu máquina excepto como cabecera de petición hacia tu propia instancia de Redmine, y el servidor no puede hacer nada que tu cuenta no pudiera hacer ya. El transporte HTTP multiusuario está planificado pero aún no está implementado: seleccionar MCP_TRANSPORT=http sale con un error claro.

El acceso local a archivos está desactivado por defecto y confinado a REDMINE_ALLOWED_DIRECTORIES cuando lo habilitas. Nada más en el servidor lee o escribe tu sistema de archivos.

Solución de problemas

Síntoma	Causa probable
El cliente no muestra herramientas	Algo distinto a JSON-RPC escribe en stdout — comprueba cualquier envoltorio
Sale inmediatamente al inicio	Falta una variable de entorno obligatoria o es inválida; el error la nombra
`401 Unauthorized`	Falta la clave API, es incorrecta, o la API REST está deshabilitada en Redmine
`403 Forbidden`	El usuario de la clave no tiene permiso para esa acción
`404 Not Found`	El id no existe o no es visible para la clave
`422 Unprocessable Entity`	Redmine rechazó la escritura — comprueba los mensajes a nivel de campo devueltos

Documentación

docs/architecture.md — diseño y ciclo de vida de las solicitudes
docs/tools.md — referencia generada por herramienta
docs/adding-a-tool.md — receta para añadir una nueva herramienta
CONTRIBUTING.md — configuración de desarrollo y guía de contribución

Desarrollo

npm install       # install dependencies
npm run dev       # watch-run the stdio server
npm test          # run the test suite
npm run build     # bundle to dist/

Licencia

MIT

Agama — Redmine MCP Server

Documentación