Backlog MCP Server

Interactúa con la API de Backlog para gestionar proyectos, incidencias, wikis, repositorios git y más.

GitHub
233
Prueba este MCPPatrocinado

Documentación

Servidor Backlog MCP

MCP Toplist MIT License Build Last Commit

📘 Guía de uso en japonés

Un servidor de Model Context Protocol (MCP) para interactuar con la API de Backlog. Este servidor proporciona herramientas para gestionar proyectos, incidencias, páginas wiki y más en Backlog a través de agentes de IA como Claude Desktop / Cline / Cursor, etc.

Características

  • Herramientas de proyectos (crear, leer, actualizar, eliminar)
  • Seguimiento de incidencias y comentarios (crear, actualizar, eliminar, listar)
  • Gestión de versiones/hitos (crear, leer, actualizar, eliminar)
  • Soporte de páginas wiki
  • Herramientas de repositorios Git y pull requests
  • Herramientas de notificaciones
  • Selección de campos para respuestas optimizadas
  • Límite de tokens para respuestas grandes

Primeros pasos

Requisitos

  • Docker
  • Una cuenta de Backlog con acceso a la API
  • Clave de API de tu cuenta de Backlog

Opción 1: Instalar mediante Docker

La forma más sencilla de usar este servidor MCP es a través de las configuraciones de MCP:

  1. Abre la configuración de MCP
  2. Navega a la sección de configuración de MCP
  3. Añade la siguiente configuración:
{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "--pull",
        "always",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Reemplaza your-domain.backlog.com con tu dominio de Backlog y your-api-key con tu clave de API de Backlog.

✅ Si no puedes usar --pull always, puedes actualizar manualmente la imagen usando:

docker pull ghcr.io/nulab/backlog-mcp-server:latest

Opción 2: Instalar mediante npx

También puedes ejecutar el servidor directamente usando npx sin clonar el repositorio. Esta es una forma conveniente de ejecutar el servidor sin una instalación completa.

  1. Abre la configuración de MCP
  2. Navega a la sección de configuración de MCP
  3. Añade la siguiente configuración:
{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["backlog-mcp-server"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Reemplaza your-domain.backlog.com con tu dominio de Backlog y your-api-key con tu clave de API de Backlog.

Opción 3: Configuración manual (Node.js)

  1. Clona e instala:

    git clone https://github.com/nulab/backlog-mcp-server.git
cd backlog-mcp-server
pnpm install
pnpm run build

  2. Crea .env a partir de la plantilla y establece las variables requeridas:

cp .env.example .env

Establece los siguientes valores en .env:

  • BACKLOG_DOMAIN=your-domain.backlog.com
  • BACKLOG_API_KEY=your-api-key
  1. Ejecuta localmente:
pnpm run dev
  1. Configura tu json para usarlo como MCP
{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["your-repository-location/build/index.js"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Transporte HTTP (Streamable HTTP)

Por defecto, el servidor usa stdio. Para ejecutar el transporte MCP Streamable HTTP en su lugar (JSON-RPC sobre HTTP, mismas herramientas que stdio), inicia con --transport http o establece MCP_TRANSPORT=http.

pnpm run build
MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
  • Endpoint: POST (y GET para flujos iniciados por el servidor) en http://<host>:<port><path> (ruta predeterminada /mcp).
  • Protocolo: MCP 2026-07-28. El protocolo no tiene estado: no hay handshake de initialize ni cabecera de mcp-session-id. Los clientes envían sus metadatos en _meta en cada solicitud y descubren capacidades mediante server/discover. Streamable HTTP también requiere la cabecera Mcp-Method (y Mcp-Name en tools/call).
  • Compatibilidad hacia atrás: Los clientes en 2025-11-25 y versiones anteriores siguen siendo atendidos en el mismo endpoint, sin estado. Debido a que no se mantiene sesión, las operaciones de sesión de 2025 (GET / DELETE con un mcp-session-id) responden 405.
  • Seguridad: El enlace predeterminado es 127.0.0.1. En un enlace de loopback simple, Host y Origin se validan ambos contra el conjunto de localhost (protección contra rebinding de DNS). Detrás de un proxy inverso, establece --http-allowed-hosts al nombre de host público; esto desactiva el valor predeterminado de localhost Origin, ya que el Origin de un cliente de navegador es su propio sitio y nunca el nombre de host de este servidor. Añade --http-allowed-origins para restringir qué orígenes de clientes pueden acceder al servidor. No expongas el puerto HTTP a redes no confiables sin autenticación y TLS; permite el uso completo de tu clave de API de Backlog a través de las herramientas MCP.

Variables de entorno (los indicadores de CLI tienen prioridad cuando ambos están establecidos):

VariableDescripción
MCP_TRANSPORTstdio (predeterminado) o http
MCP_HTTP_HOSTDirección de enlace (predeterminado 127.0.0.1)
MCP_HTTP_PORTPuerto (predeterminado 3333)
MCP_HTTP_PATHRuta de URL (predeterminado /mcp)
MCP_HTTP_JSON_RESPONSEtrue para preferir respuestas JSON sobre SSE (aplica solo a clientes 2026-07-28)
MCP_HTTP_ALLOWED_HOSTSNombres de host Host permitidos separados por comas (independientes del puerto). Requerido al enlazar a 0.0.0.0; también es la vía de escape para un enlace de loopback detrás de un proxy (protección contra rebinding de DNS)
MCP_HTTP_ALLOWED_ORIGINSNombres de host Origin permitidos separados por comas para clientes basados en navegador. Por defecto es el conjunto de localhost en un enlace de loopback simple, y sin verificación de Origin en caso contrario

Autenticación OAuth 2.0 (MCP remoto)

Al exponer el servidor MCP a través de una red, puedes habilitar la autenticación OAuth 2.0 para que cada usuario se autentique con su propia cuenta de Backlog en lugar de compartir una única clave de API.

El servidor implementa el Flujo de Autorización de Terceros MCP actuando tanto como servidor de autorización OAuth (para clientes MCP) como cliente OAuth (para Backlog).

Requisitos previos

  1. Registra una aplicación OAuth en tu espacio de Backlog:

    • Ve a tu espacio de Backlog → Configuración personal → Registrar aplicación
    • Establece la URI de redirección a <MCP_SERVER_BASE_URL>/callback (por ejemplo, https://mcp.example.com/callback)
    • Anota el ID de cliente y el Secreto de cliente

  2. Establece las siguientes variables de entorno (además de BACKLOG_DOMAIN):

VariableDescripción
BACKLOG_OAUTH_CLIENT_IDID de cliente OAuth de tu aplicación de Backlog
BACKLOG_OAUTH_CLIENT_SECRETSecreto de cliente OAuth de tu aplicación de Backlog
MCP_SERVER_BASE_URLURL pública de tu servidor MCP (por ejemplo, https://mcp.example.com)

Nota: BACKLOG_API_KEY no es requerido cuando OAuth está habilitado — cada usuario se autentica con su propia cuenta de Backlog.

Ejemplo

BACKLOG_DOMAIN=your-space.backlog.com \
BACKLOG_OAUTH_CLIENT_ID=your-client-id \
BACKLOG_OAUTH_CLIENT_SECRET=your-client-secret \
MCP_SERVER_BASE_URL=https://mcp.example.com \
node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333 \
  --http-allowed-hosts mcp.example.com

--http-allowed-hosts es requerido en la práctica al enlazar a 0.0.0.0: sin él no hay protección contra rebinding de DNS, y el servidor registra una advertencia al inicio.

El servidor expone automáticamente los siguientes endpoints OAuth cuando OAuth está habilitado:

EndpointDescripción
GET /.well-known/oauth-authorization-serverMetadatos del Servidor de Autorización OAuth (RFC 8414)
GET /.well-known/oauth-protected-resource/mcpMetadatos del Recurso Protegido OAuth (RFC 9728)
POST /registerRegistro Dinámico de Clientes (RFC 7591)
GET /authorizeEndpoint de autorización (redirige a OAuth de Backlog)
GET /callbackCallback de OAuth de Backlog
POST /tokenEndpoint de token (código de autorización y token de actualización)

Los clientes MCP que soportan la especificación de autorización MCP usarán estos endpoints automáticamente.

POST /register restringe qué URIs de redirección puede registrar un cliente. Una URI de loopback (http://localhost, http://127.0.0.1, http://[::1]) es cómo una aplicación que se ejecuta en la máquina del usuario recibe el código de autorización, y se acepta de un cliente que declara "application_type": "native" — o, cuando el campo está ausente, de uno cuyas URIs de redirección son todas de loopback. Un cliente que declara "application_type": "web", o que mezcla una URI remota https: con una de loopback sin declararse a sí mismo, es rechazado con invalid_client_metadata.

Limitaciones:

  • El modo OAuth actualmente soporta una única organización de Backlog. No es compatible con la configuración multi-organización.
  • Los registros de clientes y tokens se almacenan en memoria y se perderán al reiniciar el servidor.

Configuración de herramientas

Puedes habilitar o deshabilitar selectivamente conjuntos de herramientas específicos usando el indicador de línea de comandos --enable-toolsets o la variable de entorno ENABLE_TOOLSETS. Esto permite un mejor control sobre qué herramientas están disponibles para el agente de IA y ayuda a reducir el tamaño del contexto.

Conjuntos de herramientas disponibles

Los siguientes conjuntos de herramientas están disponibles (habilitados por defecto cuando se usa "all"):

Conjunto de herramientasDescripción
spaceHerramientas para gestionar la configuración del espacio de Backlog e información general
projectHerramientas para gestionar proyectos, categorías, campos personalizados y tipos de incidencias
issueHerramientas para gestionar incidencias y sus comentarios, versiones e hitos
wikiHerramientas para gestionar páginas wiki
gitHerramientas para gestionar repositorios Git y pull requests
notificationsHerramientas para gestionar notificaciones de usuarios
documentHerramientas para ver documentos y árboles de documentos

Especificación de conjuntos de herramientas

Puedes controlar la activación de conjuntos de herramientas de las siguientes maneras:

Usando mediante CLI:

--enable-toolsets space,project,issue

O mediante variable de entorno:

ENABLE_TOOLSETS="space,project,issue"

Si se especifica all, todos los conjuntos de herramientas disponibles se habilitarán. Este es también el comportamiento predeterminado.

Usar conjuntos de herramientas selectivos puede ser útil si la lista de conjuntos es demasiado grande para tu agente de IA o si ciertas herramientas causan problemas de rendimiento. En tales casos, deshabilitar conjuntos de herramientas no utilizados puede mejorar la estabilidad.

🧩 Consejo: El conjunto de herramientas project es altamente recomendado, ya que muchas otras herramientas dependen de los datos del proyecto como punto de entrada.

Herramientas disponibles

Conjunto de herramientas: space

Herramientas para gestionar la configuración del espacio de Backlog e información general.

  • get_space: Devuelve información sobre el espacio de Backlog.
  • get_users: Devuelve la lista de usuarios en el espacio de Backlog.
  • get_myself: Devuelve información sobre el usuario autenticado.

Conjunto de herramientas: project

Herramientas para gestionar proyectos, categorías, campos personalizados y tipos de incidencias.

  • get_project_list: Devuelve la lista de proyectos.
  • add_project: Crea un nuevo proyecto.
  • get_project: Devuelve información sobre un proyecto específico.
  • get_project_users: Devuelve la lista de usuarios en un proyecto específico.
  • update_project: Actualiza un proyecto existente.

Conjunto de herramientas: issue

Herramientas para gestionar incidencias, sus comentarios y elementos relacionados como prioridades, categorías, campos personalizados, tipos de incidencia, resoluciones y listas de seguimiento.

  • get_issue: Devuelve información sobre una incidencia específica.
  • get_issue_attachment: Descarga un adjunto de una incidencia. Lo devuelve como contenido de imagen o recurso incrustado, o como base64 con format: "base64".
  • get_issues: Devuelve una lista de incidencias.
  • count_issues: Devuelve el número de incidencias.
  • add_issue: Crea una nueva incidencia en el proyecto especificado.
  • update_issue: Actualiza una incidencia existente.
  • delete_issue: Elimina una incidencia.
  • get_issue_comments: Devuelve una lista de comentarios para una incidencia.
  • add_issue_comment: Añade un comentario a una incidencia.
  • update_issue_comment: Actualiza un comentario en una incidencia.
  • get_related_issues: Devuelve una lista de incidencias relacionadas con una incidencia específica.
  • add_related_issue: Relaciona una incidencia con otra incidencia.
  • remove_related_issue: Elimina la relación entre una incidencia y una incidencia relacionada.
  • get_priorities: Devuelve una lista de prioridades.
  • get_categories: Devuelve una lista de categorías para un proyecto.
  • add_category: Crea una nueva categoría para un proyecto.
  • get_custom_fields: Devuelve una lista de campos personalizados para un proyecto.
  • get_issue_types: Devuelve una lista de tipos de incidencia para un proyecto.
  • get_resolutions: Devuelve una lista de resoluciones de incidencias.
  • get_watching_list_items: Devuelve una lista de elementos en seguimiento para un usuario.
  • get_watching_list_count: Devuelve el número de elementos en seguimiento para un usuario.
  • add_watching: Añade un nuevo seguimiento a una incidencia.
  • update_watching: Actualiza una nota de seguimiento existente.
  • delete_watching: Elimina un seguimiento de una incidencia.
  • mark_watching_as_read: Marca un seguimiento como leído.
  • get_version_milestone_list: Devuelve una lista de hitos de versión para un proyecto.
  • add_version_milestone: Crea un nuevo hito de versión para un proyecto.
  • update_version_milestone: Actualiza un hito de versión existente.
  • delete_version_milestone: Elimina un hito de versión.

Conjunto de herramientas: wiki

Herramientas para gestionar páginas wiki.

  • get_wiki_pages: Devuelve una lista de páginas Wiki.
  • get_wikis_count: Devuelve el número de páginas wiki en un proyecto.
  • get_wiki: Devuelve información sobre una página wiki específica.
  • add_wiki: Crea una nueva página wiki.

Conjunto de herramientas: git

Herramientas para gestionar repositorios Git y solicitudes de extracción.

  • get_git_repositories: Devuelve una lista de repositorios Git para un proyecto.
  • get_git_repository: Devuelve información sobre un repositorio Git específico.
  • get_pull_requests: Devuelve una lista de solicitudes de extracción para un repositorio.
  • get_pull_requests_count: Devuelve el número de solicitudes de extracción para un repositorio.
  • get_pull_request: Devuelve información sobre una solicitud de extracción específica.
  • add_pull_request: Crea una nueva solicitud de extracción.
  • update_pull_request: Actualiza una solicitud de extracción existente.
  • get_pull_request_comments: Devuelve una lista de comentarios para una solicitud de extracción.
  • add_pull_request_comment: Añade un comentario a una solicitud de extracción.
  • update_pull_request_comment: Actualiza un comentario en una solicitud de extracción.

Conjunto de herramientas: notifications

Herramientas para gestionar notificaciones de usuario.

  • get_notifications: Devuelve una lista de notificaciones.
  • get_notifications_count: Devuelve el número de notificaciones.
  • reset_unread_notification_count: Restablece el contador de notificaciones no leídas.
  • mark_notification_as_read: Marca una notificación como leída.

Conjunto de herramientas: document

Herramientas para gestionar documentos y árboles de documentos en proyectos de Backlog.

  • get_document_tree: Devuelve el árbol jerárquico de documentos de un proyecto, incluyendo carpetas y ne
  • get_documents: Devuelve una lista plana de documentos en un proyecto o carpeta.
  • get_document: Devuelve información detallada sobre un documento específico, incluyendo metadatos, contenido y

Ejemplos de uso

Una vez que el servidor MCP está configurado en los agentes de IA, puedes usar las herramientas directamente en tus conversaciones. Aquí tienes algunos ejemplos:

  • Listar proyectos
Could you list all my Backlog projects?
  • Crear una nueva incidencia
Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"
  • Obtener detalles del proyecto
Show me the details of the PROJECT-KEY project
  • Trabajar con repositorios Git
List all Git repositories in the PROJECT-KEY project
  • Gestionar solicitudes de extracción
Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project

Create a new pull request from branch "feature/new-feature" to "main" in the repository "repo-name" of PROJECT-KEY project
  • Elementos en seguimiento
Show me all items I'm watching

Sobrescribir descripciones de herramientas

Puedes sobrescribir las descripciones de las herramientas creando un archivo .backlog-mcp-serverrc.json en tu directorio de inicio.

Casi todas estas cadenas son las descripciones de herramientas y parámetros que el modelo lee cuando decide qué herramienta llamar y cómo completar sus argumentos, por lo que sobrescribirlas es una forma de orientar la selección de herramientas — por ejemplo, para distinguir dos herramientas similares, o para añadir una regla que siga tu equipo — más que una forma de cambiar el idioma de las respuestas que obtienes. El modelo responde en el idioma en el que preguntes, independientemente del idioma en el que estén escritas estas descripciones.

Un pequeño número de claves son mensajes de error de validación (por ejemplo, PROJECT_ID_OR_KEY_REQUIRED). Estos se devuelven en el resultado de la herramienta cuando una llamada es rechazada, por lo que pueden llegar a ti a través de la respuesta del modelo.

El archivo debe contener un objeto JSON con los nombres de las herramientas como claves y las nuevas descripciones como valores.
Por ejemplo:

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description",
  "TOOL_CREATE_PROJECT_DESCRIPTION": "Create a new project in Backlog"
}

Cuando el servidor se inicia, determina la descripción final de cada herramienta según la siguiente prioridad:

  1. Variables de entorno (p. ej., BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION)
  2. Entradas en .backlog-mcp-serverrc.json - Formatos de archivo de configuración admitidos: .json, .yaml, .yml
  3. Valores predeterminados integrados

Los valores vacíos o que no sean cadenas se ignoran en todos los niveles, y se utiliza el valor predeterminado integrado en su lugar.

Configuración de ejemplo:

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "-v",
        "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Exportar descripciones actuales

Puedes exportar las descripciones actuales (incluyendo cualquier sobrescritura) ejecutando el binario con la bandera --export-descriptions. Esta bandera se llamaba anteriormente --export-translations; el nombre antiguo sigue funcionando pero imprime un aviso de obsolescencia y se eliminará en una versión futura.

Esto imprime cada clave que se resuelve mientras se construye la lista de herramientas, con su valor actual, incluyendo cualquier personalización que hayas realizado. Esto cubre todas las descripciones de herramientas y parámetros, y es la forma práctica de descubrir los nombres de las claves.

No cubre los mensajes de error de validación, porque esas claves solo se resuelven cuando una llamada es realmente rechazada. Siguen siendo sobrescribibles con las mismas reglas; solo tienes que leerlas del código fuente.

Ejemplo:

docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions

o

npx github:nulab/backlog-mcp-server --export-descriptions

Uso de variables de entorno

Alternativamente, puedes sobrescribir las descripciones de herramientas mediante variables de entorno.

Los nombres de las variables de entorno se basan en las claves de las herramientas, con el prefijo BACKLOGMCP y escritos en mayúsculas.

Ejemplo: Para sobrescribir TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "BACKLOG_DOMAIN",
        "-e", "BACKLOG_API_KEY",
        "-e", "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION"
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key",
        "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description"
      }
    }
  }
}

El servidor carga el archivo de configuración de forma síncrona al iniciarse.

Las variables de entorno siempre tienen prioridad sobre el archivo de configuración.

Funciones avanzadas

Prefijo de nombres de herramientas

Añade un prefijo a los nombres de las herramientas con:

--prefix backlog_

o mediante variable de entorno:

PREFIX="backlog_"

Esto es especialmente útil si estás usando varios servidores MCP o herramientas en el mismo entorno y quieres evitar colisiones de nombres. Por ejemplo, get_project puede convertirse en backlog_get_project para distinguirlo de herramientas con nombres similares proporcionadas por otros servicios.

Optimización de respuestas y límites de tokens

Selección de campos

--optimize-response

O variable de entorno:

OPTIMIZE_RESPONSE=1

Las herramientas que devuelven una lista aceptan entonces un parámetro opcional fields: una lista de nombres de campos de nivel superior del resultado de esa propia herramienta, publicada como un enum para que un nombre que la herramienta no tenga sea rechazado en lugar de ignorado. Las herramientas que devuelven un único registro no lo reciben — el parámetro cuesta esquema en cada sesión, y un registro no tiene casi nada que recortar.

get_project(projectIdOrKey: "PROJECT-KEY", fields: ["name", "key", "description"])

Omitir fields devuelve el resultado completo. La selección tiene una profundidad de un nivel: nombrar un campo de objeto o array lo devuelve completo.

Beneficios:

  • Reducir el tamaño de la respuesta solicitando solo los campos necesarios
  • Centrarse en puntos de datos específicos
  • Mejorar el rendimiento para respuestas grandes

Límite de tokens

Las respuestas grandes se limitan automáticamente para evitar superar los límites de tokens:

  • Límite predeterminado: 50 000 tokens
  • Configurable mediante la variable de entorno MAX_TOKENS
  • Las respuestas que superan el límite se truncan con un mensaje

Puedes cambiar esto usando:

MAX_TOKENS=10000

Si una respuesta supera el límite, se truncará con una advertencia.

Nota: Esta es una mitigación de mejor esfuerzo, no una garantía de cumplimiento.

Registro de actividad

El servidor registra en stderr (stdout transporta el flujo JSON-RPC en el transporte stdio).

VariableDescripción
LOG_LEVELfatal, error, warn, info, debug, trace o silent. El valor predeterminado es error cuando NODE_ENV es production — que también es el valor predeterminado cuando NODE_ENV no está definido — y debug en caso contrario. Un valor no reconocido se informa y se utiliza el valor predeterminado.

NODE_ENV sigue seleccionando el formato de salida: cualquier valor distinto de production cambia a salida pino-pretty legible por humanos cuando ese paquete está disponible. Usa LOG_LEVEL, no NODE_ENV, para cambiar cuánto se registra, de modo que un despliegue mantenga JSON estructurado:

pino-pretty es una dependencia de desarrollo, por lo que ni el paquete npm publicado ni la imagen de contenedor incluyen una copia. En esos casos, los registros son JSON estructurado independientemente de lo que diga NODE_ENV, y LOG_LEVEL es la única configuración que cambia la salida.

LOG_LEVEL=info node build/index.js --transport http

Ejemplo completo de configuración personalizada

Esta sección demuestra la configuración avanzada usando múltiples variables de entorno. Estas son funciones experimentales y pueden no ser compatibles con todos los clientes MCP. Esto no forma parte de la especificación estándar de MCP y debe usarse con precaución.

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "-e",
        "MAX_TOKENS",
        "-e",
        "OPTIMIZE_RESPONSE",
        "-e",
        "PREFIX",
        "-e",
        "ENABLE_TOOLSETS",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key",
        "MAX_TOKENS": "10000",
        "OPTIMIZE_RESPONSE": "1",
        "PREFIX": "backlog_",
        "ENABLE_TOOLSETS": "space,project,issue"
      }
    }
  }
}

Desarrollo

Ejecutar pruebas

pnpm test

Añadir nuevas herramientas

  1. Crea un nuevo archivo en src/tools/ siguiendo el patrón de las herramientas existentes
  2. Crea un archivo de prueba correspondiente
  3. Añade la nueva herramienta a src/tools/tools.ts
  4. Compila y prueba tus cambios

Opciones de línea de comandos

El servidor admite varias opciones de línea de comandos:

  • --transport stdio|http: Transporte MCP (predeterminado: stdio). Use http para Streamable HTTP.
  • --http-host, --http-port, --http-path: Dirección de enlace HTTP, puerto y ruta (valores predeterminados: 127.0.0.1, 3333, /mcp).
  • --http-json-response: Preferir respuestas JSON sobre SSE. Se aplica solo a clientes 2026-07-28; la ruta 2025-11-25 compatible con versiones anteriores se sirve con la configuración de respuesta predeterminada del SDK.
  • --http-allowed-hosts: Lista separada por comas de nombres de host Host permitidos (independiente del puerto). Necesario al enlazar a todas las interfaces, o en un enlace de bucle local detrás de un proxy inverso.
  • --http-allowed-origins: Lista separada por comas de nombres de host Origin permitidos para clientes basados en navegador. Se establece por defecto en el conjunto de localhost en un enlace de bucle local simple, y sin verificación de Origin en caso contrario.
  • --export-descriptions: Exportar las claves y valores de descripción resueltos al construir la lista de herramientas. Anteriormente se llamaba --export-translations; esa ortografía aún funciona como alias obsoleto y se eliminará en una versión futura.
  • --optimize-response: Agregar un parámetro fields a cada herramienta para seleccionar qué campos de resultado devolver.
  • --max-tokens=NUMBER: Establecer el límite máximo de tokens para las respuestas.
  • --prefix=STRING: Prefijo de cadena opcional para anteponer a todos los nombres de herramientas (predeterminado: "").
  • --enable-toolsets <toolsets...>: Especificar qué conjuntos de herramientas habilitar (separados por comas o múltiples argumentos). El valor predeterminado es "all". Ejemplo: --enable-toolsets space,project o --enable-toolsets issue --enable-toolsets git Conjuntos de herramientas disponibles: space, project, issue, wiki, git, notifications.

Ejemplo:

node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue

Ejemplo HTTP:

node build/index.js --transport http --http-port 3333 --http-path /mcp

Soporte Multi-Organización

Este servidor se puede configurar para acceder a múltiples organizaciones de Backlog desde una única instancia del servidor MCP.

Configuración

Configure un par de variables de entorno por organización y establezca una organización predeterminada:

BACKLOG_DEFAULT_ORG=COMPANY_A
BACKLOG_ORG_COMPANY_A_DOMAIN=company-a.backlog.com
BACKLOG_ORG_COMPANY_A_API_KEY=your-company-a-api-key
BACKLOG_ORG_COMPANY_B_DOMAIN=company-b.backlog.com
BACKLOG_ORG_COMPANY_B_API_KEY=your-company-b-api-key

Esto funciona tanto si las variables provienen de un .env local, de su entorno de shell o de un bloque de configuración env del cliente MCP.

Ejemplo de configuración MCP:

{
  "env": {
    "BACKLOG_DEFAULT_ORG": "COMPANY_A",
    "BACKLOG_ORG_COMPANY_A_DOMAIN": "company-a.backlog.com",
    "BACKLOG_ORG_COMPANY_A_API_KEY": "your-company-a-api-key",
    "BACKLOG_ORG_COMPANY_B_DOMAIN": "company-b.backlog.com",
    "BACKLOG_ORG_COMPANY_B_API_KEY": "your-company-b-api-key"
  }
}

Si no se establecen variables de entorno multi-organización, el servidor recurre a la configuración existente de organización única:

BACKLOG_DOMAIN=your-domain.backlog.com
BACKLOG_API_KEY=your-api-key

Uso de Herramientas

Cuando se configuran variables de entorno multi-organización, todas las herramientas normales aceptan un campo de entrada opcional organization. Cuando se proporciona, la llamada a la herramienta se enruta a esa organización de Backlog.

En modo de organización única, el campo no se publica, ya que solo habría una organización a la que enrutar. Omitirlo mantiene aproximadamente 8 KB del esquema de herramientas fuera de cada respuesta tools/list.

Ejemplos:

{
  "organization": "COMPANY_B",
  "projectKey": "PROJECT"
}

Si se omite organization:

  • se utiliza la organización nombrada por BACKLOG_DEFAULT_ORG
  • si las variables de entorno multi-organización están presentes y falta BACKLOG_DEFAULT_ORG, el servidor falla al iniciar

Descubrimiento de Organizaciones

En modo multi-organización, el servidor proporciona una herramienta list_organizations que devuelve los nombres de las organizaciones configuradas, sus dominios y cuál es la predeterminada. No se registra en modo de organización única.

Ejemplo de respuesta:

[
  {
    "name": "COMPANY_A",
    "domain": "company-a.backlog.com",
    "isDefault": true
  },
  {
    "name": "COMPANY_B",
    "domain": "company-b.backlog.com",
    "isDefault": false
  }
]

Notas

  • Para el modo multi-organización, cada organización debe definir tanto BACKLOG_ORG_<NAME>_DOMAIN como BACKLOG_ORG_<NAME>_API_KEY.
  • La parte <NAME> es el nombre de la organización expuesto a través de la entrada de la herramienta organization y list_organizations.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Tenga en cuenta: Esta herramienta se proporciona bajo la Licencia MIT sin ninguna garantía ni soporte oficial.
Úsela bajo su propio riesgo después de revisar el contenido y determinar su idoneidad para sus necesidades.
Si encuentra algún problema, repórtelo a través de GitHub Issues.