Backlog MCP Server

Un servidor MCP para interactuar con la API de Backlog, una herramienta de gestión de proyectos y colaboración.

GitHub
14
Prueba este MCPPatrocinado

Documentación

Servidor Backlog MCP (mcp-backlog-server)

codecov

mcp-backlog-server es un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con la API de Backlog. Este servidor permite que clientes compatibles con MCP (como asistentes de IA) utilicen las funcionalidades de Backlog.

Instalación

Usando Homebrew (Recomendado para macOS/Linux)

La forma más fácil de instalar es mediante Homebrew:

# Add the tap (only needed once)
brew tap safx/tap

# Install the tools
brew install mcp-backlog-server  # MCP server for AI assistants
brew install blg                 # Backlog CLI tool (Optional)

Para actualizar a la última versión:

brew update
brew upgrade mcp-backlog-server
brew upgrade blg

Para desinstalar:

brew uninstall mcp-backlog-server
brew uninstall blg
brew untap safx/tap  # Optional: remove the tap

Métodos de Instalación Alternativos

Para otras plataformas o si prefieres no usar Homebrew:

  • Binarios precompilados: Descarga desde la página de versiones
  • Compilar desde el código fuente: Clona el repositorio y ejecuta cargo build --release

Ejemplo de Configuración para Cliente MCP

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "backlog": {
      "command": "/path/to/target/release/mcp-backlog-server",
      "args": [],
      "env": {
        "BACKLOG_BASE_URL": "https://your-space.backlog.com",
        "BACKLOG_API_KEY": "YOUR_BACKLOG_API_KEY",
        "BACKLOG_PROJECTS": "PROJ,DEMO",
        "BACKLOG_PREFIX": "backlog_"
      }
    }
  }
}

Cline

Añade lo siguiente a tu configuración MCP de Cline:

{
  "mcpServers": {
    "backlog_mcp_server": {
      "autoApprove": [],
      "disabled": false,
      "timeout": 60,
      "command": "/path/to/target/release/mcp-backlog-server",
      "args": [],
      "env": {
        "BACKLOG_BASE_URL": "https://your-space.backlog.com",
        "BACKLOG_API_KEY": "YOUR_BACKLOG_API_KEY",
        "BACKLOG_PROJECTS": "PROJ,DEMO",
        "BACKLOG_PREFIX": "backlog_"
      },
      "transportType": "stdio"
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "backlog_mcp_server": {
      "command": "/path/to/target/release/mcp-backlog-server",
      "timeout": 10000,
      "args": [],
      "env": {
        "BACKLOG_BASE_URL": "https://your-space.backlog.com",
        "BACKLOG_API_KEY": "YOUR_BACKLOG_API_KEY",
        "BACKLOG_PROJECTS": "PROJ,DEMO",
        "BACKLOG_PREFIX": "backlog_"
      }
    }
  }
}

Nota: El nombre de dominio debe ser: backlog.com, backlog.jp o backlogtool.com

Herramientas Disponibles

Las siguientes herramientas están agrupadas por sus respectivos módulos:

Resumen de Herramientas

Con la configuración predeterminada, tienes acceso a 36 herramientas para la automatización de Backlog:

  • Documentos (5 herramientas): Ver árboles de documentos, obtener detalles, descargar archivos adjuntos, añadir documentos, eliminar documentos
  • Git/Solicitudes de extracción (8 herramientas): Gestionar repositorios, solicitudes de extracción, comentarios y archivos adjuntos
  • Problemas (12 herramientas): Ver, crear, actualizar problemas, gestionar comentarios, archivos adjuntos, archivos compartidos y prioridades
  • Proyectos (3 herramientas): Obtener estado del proyecto, tipos de problema y definiciones de campos personalizados
  • Archivos Compartidos (2 herramientas): Explorar y descargar archivos compartidos del proyecto
  • Usuarios (1 herramienta): Listar usuarios del espacio
  • Wikis (5 herramientas): Gestionar páginas wiki, archivos adjuntos y actualizaciones de contenido

El servidor incluye tanto operaciones de lectura para recopilar información como operaciones de escritura para realizar acciones.

Nota: Los nombres de las herramientas siguen un patrón category_resource_action (por ejemplo, issue_details_get, wiki_update) para permitir el filtrado basado en categorías con --allowedTools (por ejemplo, claude --allowedTools "mcp__backlog__issue_*").

Herramientas de Documentos

  • document_details_get: Recupera detalles de un documento específico de Backlog
  • document_attachment_download: Descarga un archivo adjunto de documento
  • document_tree_get: Obtiene el árbol de documentos de un proyecto especificado
  • document_add: Añade un nuevo documento a un proyecto de Backlog
  • document_delete: Elimina un documento de Backlog

Herramientas de Git

  • git_repository_list_get: Obtiene una lista de repositorios Git para un proyecto especificado
  • git_repository_details_get: Obtiene detalles de un repositorio Git específico
  • git_pr_list_get: Obtiene una lista de solicitudes de extracción para un repositorio especificado
  • git_pr_details_get: Obtiene detalles de una solicitud de extracción específica
  • git_pr_attachment_list_get: Obtiene una lista de archivos adjuntos para una solicitud de extracción específica
  • git_pr_comment_list_get: Obtiene una lista de comentarios para una solicitud de extracción específica
  • git_pr_attachment_download: Descarga un archivo adjunto de solicitud de extracción
  • git_pr_comment_add: Añade un comentario a una solicitud de extracción específica

Herramientas de Problemas

  • issue_details_get: Recupera detalles de un problema específico de Backlog
  • issue_milestone_list_get: Recupera una lista de versiones (hitos) para un proyecto especificado
  • issue_list_by_milestone_get: Recupera una lista de problemas asociados con un hito especificado
  • issue_update: Actualiza un problema de Backlog incluyendo resumen, descripción y campos personalizados
  • issue_comment_list_get: Obtiene comentarios de un problema específico
  • issue_attachment_list_get: Obtiene una lista de archivos adjuntos para un problema especificado
  • issue_attachment_download: Descarga un archivo adjunto de problema
  • issue_shared_file_list_get: Obtiene una lista de archivos compartidos vinculados a un problema especificado
  • issue_comment_update: Actualiza un comentario existente en un problema de Backlog
  • issue_add: Crea un nuevo problema en un proyecto de Backlog con soporte para campos personalizados
  • issue_comment_add: Añade un comentario a un problema específico
  • issue_priority_list_get: Obtiene una lista de tipos de prioridad disponibles en el espacio

Herramientas de Proyectos

  • project_status_list_get: Obtiene una lista de estados para un proyecto especificado
  • project_issue_type_list_get: Obtiene una lista de tipos de problema para un proyecto especificado
  • project_custom_field_list_get: Obtiene una lista de campos personalizados definidos para un proyecto especificado

Herramientas de Archivos Compartidos

  • file_shared_list_get: Obtiene una lista de archivos compartidos para un directorio de proyecto especificado
  • file_shared_download: Descarga un archivo compartido

Herramientas de Usuarios

  • user_list_get: Obtiene una lista de usuarios en el espacio

Herramientas de Wiki

  • wiki_list_get: Obtiene una lista de páginas wiki
  • wiki_details_get: Obtiene información detallada sobre una página wiki específica
  • wiki_attachment_list_get: Obtiene una lista de archivos adjuntos para una página wiki especificada
  • wiki_attachment_download: Descarga un archivo adjunto de una página wiki
  • wiki_update: Actualiza una página wiki

Funciones de Descarga de Archivos

Todas las herramientas de descarga de archivos (document_attachment_download, issue_attachment_download, git_pr_attachment_download, wiki_attachment_download y file_shared_download) admiten detección y manejo de formato:

Detección de Formato

  • Imágenes: Los archivos con tipo de contenido image/* se detectan y se devuelven como imágenes codificadas en base64 mediante rmcp::model::Content::image
  • Texto: Los archivos con tipos de contenido basados en texto (text/*, application/json, application/xml, etc.) o archivos que contienen texto UTF-8 válido se devuelven como texto plano mediante rmcp::model::Content::text
  • Bytes sin procesar: Todos los demás archivos se devuelven como objetos JSON con contenido codificado en base64, nombre de archivo y tipo MIME

Anulación Manual de Formato

Puedes especificar explícitamente el formato usando el parámetro opcional format:

  • "image": Forzar el tratamiento como imagen (valida el tipo de contenido)
  • "text": Forzar el tratamiento como texto (valida la codificación UTF-8)
  • "raw": Forzar el tratamiento como bytes sin procesar (sin validación)

Detección de Tipo de Contenido

El sistema utiliza múltiples estrategias para determinar si un archivo es texto:

  • Análisis del encabezado Content-Type
  • Verificación de validez UTF-8
  • Análisis de composición de caracteres (gráficos, espacios en blanco y caracteres UTF-8 válidos)

Cómo Compilar

# Default build (includes all writable features)
cargo build --package mcp-backlog-server

Indicadores de Funciones

El servidor MCP admite múltiples indicadores de funciones para habilitar diferentes operaciones de escritura:

  • issue_writable (habilitado por defecto)

    • Habilita: herramientas issue_update, issue_comment_update, issue_add y issue_comment_add
    • Permite que los agentes de IA creen problemas, modifiquen el contenido de problemas y gestionen comentarios

  • git_writable (habilitado por defecto)

    • Habilita: herramienta git_pr_comment_add
    • Permite que los agentes de IA añadan comentarios a solicitudes de extracción

  • wiki_writable (habilitado por defecto)

    • Habilita: herramienta wiki_update
    • Permite que los agentes de IA actualicen el contenido de páginas wiki, nombres y configuraciones de notificación

  • document_writable (habilitado por defecto)

    • Habilita: herramientas document_add y document_delete
    • Permite que los agentes de IA creen y eliminen documentos

Configuración de Compilación

# Read-only mode (no write operations)
cargo build --package mcp-backlog-server --no-default-features

# Selective features
cargo build --package mcp-backlog-server --features issue_writable
cargo build --package mcp-backlog-server --features "issue_writable,git_writable"
cargo build --package mcp-backlog-server --features "issue_writable,git_writable,wiki_writable,document_writable"

Configuración

Para ejecutar este servidor, se deben establecer las siguientes variables de entorno:

  • BACKLOG_BASE_URL: La URL de tu espacio Backlog (por ejemplo, https://your-space.backlog.com)
  • BACKLOG_API_KEY: Tu clave de API de Backlog. Puedes emitir una desde tu página de configuración personal en Backlog.

Variables de entorno opcionales:

  • BACKLOG_PROJECTS: Lista separada por comas de claves de proyecto permitidas (por ejemplo, MFP,DEMO,TEST). Cuando se establece, el servidor solo permitirá el acceso a los proyectos especificados. Si no se establece, todos los proyectos accesibles con la clave de API están disponibles.
  • BACKLOG_PREFIX: Prefijo personalizado para nombres de herramientas (predeterminado: backlog_). Por ejemplo, establecer BACKLOG_PREFIX="" elimina el prefijo, haciendo que las herramientas sean accesibles como issue_details_get en lugar de backlog_issue_details_get. Establecer BACKLOG_PREFIX="my_" cambia las herramientas a my_issue_details_get.

Se espera que estas variables de entorno sean pasadas por el sistema cliente MCP al iniciar el servidor.

Ejecución (para pruebas locales)

Después de establecer las variables de entorno, puedes ejecutar el servidor directamente con el siguiente comando:

# Default run with all features
BACKLOG_BASE_URL="https://your-space.backlog.com" \
BACKLOG_API_KEY="your_backlog_api_key" \
cargo run --package mcp-backlog-server