redmine-mcp

Un servidor Model Context Protocol sin estado para Redmine. Colóquelo frente a cualquier instancia de Redmine y permita que Claude (o cualquier cliente LLM compatible con MCP) lea y escriba incidencias, registre tiempo, explore la wiki y busque proyectos en nombre del usuario, con la propia clave de API de cada usuario.

• Sin estado: sin base de datos, sin sesiones, sin secretos compartidos. El servidor reenvía cada solicitud a Redmine utilizando la clave de API que la acompaña.

• Un servidor, muchos usuarios: lo único que configura el operador es la REDMINE_URL ascendente. Cada cliente MCP proporciona su propia X-Redmine-API-Key. Los permisos son los que Redmine indique.

• Cobertura: incidencias (CRUD + notas), proyectos, membresías, usuarios, registros de tiempo, wiki (PUT-upsert), archivos adjuntos (carga + descarga), búsqueda de texto completo, estados, rastreadores, categorías, campos personalizados, enumeraciones.

Inicio rápido

Local (uv)

uv sync
REDMINE_URL=https://redmine.example.com uv run redmine-mcp

El endpoint de MCP ahora está en http://127.0.0.1:8080/mcp.

Contenedor (GHCR)

docker run --rm -p 8080:8080 \
  -e REDMINE_URL=https://redmine.example.com \
  ghcr.io/kalvadtech/redmine-mcp:latest

La imagen es Alpine multietapa, se ejecuta como un usuario sin privilegios (non-root) y expone el puerto 8080.

Related MCP server: Redmine MCP Server

Conéctelo a su cliente MCP

Encuentre su clave de API de Redmine en Mi cuenta > Clave de acceso a la API. Ambos clientes a continuación se comunican con el mismo endpoint MCP a través de HTTP transmitible; no se requiere ninguna otra configuración de cliente.

Claude Code

.mcp.json en la raíz de su proyecto:

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "X-Redmine-API-Key": "your-40-char-key"
      }
    }
  }
}

opencode

opencode.json en la raíz de su proyecto (o en su directorio de configuración de opencode):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "redmine": {
      "type": "remote",
      "url": "http://127.0.0.1:8080/mcp",
      "enabled": true,
      "headers": {
        "X-Redmine-API-Key": "{env:REDMINE_API_KEY}"
      }
    }
  }
}

opencode admite la interpolación {env:VAR} en headers, por lo que la clave de API permanece fuera del archivo de configuración: REDMINE_API_KEY=... opencode.

Configuración

Flags de CLI en redmine-mcp:

--host        bind address (default 127.0.0.1)
--port        port (default 8080)
--log-level   uvicorn log level (default info)

El servidor falla rápidamente al arrancar si falta REDMINE_URL o no es http(s).

Modelo de autenticación

La URL de Redmine no es proporcionada por el usuario; es fija por despliegue a través de REDMINE_URL. Esto elimina el riesgo de SSRF: los clientes no pueden apuntar el servidor a hosts arbitrarios.

La única credencial que envía un cliente es su propia clave de API de Redmine en el encabezado X-Redmine-API-Key. El servidor la reenvía como el mismo encabezado a Redmine (por lo que no aparece en los registros de acceso de Redmine como una cadena de consulta), la usa para realizar una solicitud y luego la descarta. No hay almacenamiento en caché, ni cuenta de servicio compartida, ni suplantación de identidad.

Herramientas

59 herramientas cubren cada familia de recursos que Redmine expone a través de su API REST. Las herramientas de lista devuelven {items, total_count, limit, offset} para una paginación sencilla.

Incidencias

• list_issues (proyecto, estado, asignado, rastreador, categoría, versión, consulta guardada, consulta de texto libre, orden, incluir)

• get_issue (incluir: diarios, archivos adjuntos, relaciones, hijos, observadores)

• create_issue (incl. tokens de uploads, custom_fields, watcher_user_ids)

• update_issue (incl. notes, private_notes)

• add_issue_note (envoltorio ligero)

• delete_issue

Relaciones de incidencias

• list_issue_relations, get_relation, create_issue_relation (relaciona / bloquea / precede / etc., con delay para precede/sigue), delete_relation

Diarios (notas de incidencia)

• update_journal_note - edita el texto o la privacidad de una nota existente. Use add_issue_note para añadir una nueva nota.

Proyectos y versiones

• list_projects, get_project

• list_versions, get_version, create_version, update_version, delete_version

Membresías

• list_memberships, get_membership, add_project_member (usuario o grupo), update_membership, remove_membership

Usuarios, mi cuenta, grupos, roles

• list_users, get_user (acepta la cadena literal "current")

• get_my_account, update_my_account

• list_groups, get_group, create_group, update_group, delete_group, add_user_to_group, remove_user_from_group

• list_roles, get_role (con permisos)

Registros de tiempo

• list_time_entries (rangos de fechas, usuario, proyecto, incidencia)

• create_time_entry (incidencia o proyecto, horas, actividad, spent_on, comentarios)

• update_time_entry, delete_time_entry

Wiki

• list_wiki_pages, get_wiki_page (con versión)

• create_or_update_wiki_page (PUT-upsert)

• delete_wiki_page

Archivos adjuntos y archivos

• get_attachment, download_attachment (limitado a 25 MiB, salida en base64)

• upload_attachment (devuelve un token para adjuntar mediante uploads en create_issue / update_issue)

• list_files, upload_file (carga única + adjuntar al área de Archivos de un proyecto, con version_id y descripción opcionales)

Noticias, consultas, búsqueda y metadatos

• list_news (entre proyectos o por proyecto)

• list_queries (consultas guardadas; pase el id como query_id a list_issues)

• search (texto completo en incidencias, noticias, documentos, wiki, etc.)

• list_issue_statuses, list_trackers, list_issue_categories, list_custom_fields

• list_issue_priorities, list_time_entry_activities, list_document_categories

Despliegue

Para una sola instancia de Redmine, ejecute un contenedor por entorno:

docker run -d --name redmine-mcp \
  --restart unless-stopped \
  -p 8080:8080 \
  -e REDMINE_URL=https://redmine.example.com \
  ghcr.io/kalvadtech/redmine-mcp:latest

Colóquelo detrás de su proxy inverso habitual y terminación TLS. El protocolo MCP es solo HTTP en el lado del servidor; los usuarios obtienen TLS a través de su proxy.

Para múltiples instancias de Redmine, ejecute un contenedor por instancia con su propia REDMINE_URL y enrute por nombre de host / ruta en el proxy.

Desarrollo

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

El conjunto de pruebas está completamente fuera de línea y utiliza respx para simular la API HTTP de Redmine. No hay pruebas de integración contra un Redmine en vivo; traiga el suyo.

Contribución

Las solicitudes de extracción (pull requests) son bienvenidas. Por favor:

• siga Conventional Commits,

• mantenga los cambios concisos y bien definidos (un cambio lógico por commit),

• añada o actualice pruebas para cualquier cambio de comportamiento,

• ejecute pytest, ruff y mypy correctamente antes de abrir el PR.

Licencia

MIT (c) 2026 Kalvad.