Backlog MCP Server

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

GitHub
225
Prueba este MCPPatrocinado

Documentación

Backlog MCP Server

MCP Toplist MIT License Build Last Commit

📘 日本語でのご利用ガイド

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: Instalación 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. Ve 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 la imagen manualmente usando:

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

Opción 2: Instalación 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. Ve 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 necesarias:

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 initialize ni cabecera mcp-session-id. Los clientes envían sus metadatos en _meta en cada solicitud y descubren las 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. Como no se mantiene ninguna 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 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 (las banderas de CLI tienen prioridad cuando ambas están establecidas):

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 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, el conjunto de localhost en un enlace loopback simple, y sin verificación 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 (p. ej., 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 (p. ej., https://mcp.example.com)

Nota: BACKLOG_API_KEY no es necesario 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 necesario 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 iniciar.

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 de recurso protegido OAuth (RFC 9728)
POST /registerRegistro dinámico de clientes (RFC 7591)
GET /authorizeEndpoint de autorización (redirige a OAuth de Backlog)
GET /callbackDevolución de llamada OAuth de Backlog
POST /tokenEndpoint de token (código de autorización y token de actualización)

Los clientes MCP que admiten 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 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 loopback. Un cliente que declara "application_type": "web", o que mezcla una URI remota https: con una loopback sin declararse, es rechazado con invalid_client_metadata.

Limitaciones:

  • El modo OAuth actualmente admite una única organización de Backlog. No es compatible con la configuración multi-organización.
  • Los registros de clientes y los 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 la bandera 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, hitos de versión
wikiHerramientas para gestionar páginas wiki
gitHerramientas para gestionar repositorios Git y pull requests
notificationsHerramientas para gestionar notificaciones de usuario
documentHerramientas para ver documentos y árboles de documentos

Especificación de conjuntos de herramientas

Puedes controlar la activación de los 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, se habilitarán todos los conjuntos de herramientas disponibles. Este también es 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 están causando problemas de rendimiento. En tales casos, deshabilitar los conjuntos de herramientas no utilizados puede mejorar la estabilidad.

🧩 Consejo: el conjunto de herramientas project es muy 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.
  • delete_project: Elimina un proyecto.

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_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.
  • 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, incluidas carpetas y
  • get_documents: Devuelve una lista plana de documentos en un proyecto o carpeta.
  • get_document: Devuelve información detallada sobre un documento específico, incluidos metadatos, contenido y

Ejemplos de uso

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

  • Listado de proyectos
Could you list all my Backlog projects?
  • Creación de una nueva incidencia
Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"
  • Obtención de detalles del proyecto
Show me the details of the PROJECT-KEY project
  • Trabajo con repositorios Git
List all Git repositories in the PROJECT-KEY project
  • Gestión de 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

Anulación de descripciones de herramientas

Puedes anular 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 anularlas es una forma de orientar la selección de herramientas — por ejemplo, para desambiguar 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 en cambio mensajes de error de validación (por ejemplo, PROJECT_ID_OR_KEY_REQUIRED). Esos se devuelven en el resultado de la herramienta cuando se rechaza una llamada, 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"
      }
    }
  }
}

Exportación de descripciones actuales

Puedes exportar las descripciones actuales (incluidas las anulaciones) ejecutando el binario con la bandera --export-descriptions. Esta bandera se llamaba anteriormente --export-translations; el nombre antiguo sigue funcionando pero muestra 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, incluidas las personalizaciones 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 se rechaza realmente. Siguen siendo anulables 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 anular 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 anular 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

Prefijado 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 enumeración 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 solo registro casi no tiene nada que recortar.

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

Omitir fields devuelve el resultado completo. La selección es de un nivel de profundidad: nombrar un campo de objeto o matriz 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

Limitación 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 aplicación garantizada.

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

Ejecución de 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). Usa 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: Prefiere 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: Nombres de host Host permitidos separados por comas (independientes 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: Nombres de host Origin permitidos separados por comas para clientes basados en navegador. El valor predeterminado es el conjunto de localhost en un enlace de bucle local simple, y sin comprobación de Origin en caso contrario.
  • --export-descriptions: Exporta las claves y valores de descripción resueltos al construir la lista de herramientas. Se llamaba --export-translations; esa grafía sigue funcionando como alias obsoleto y se eliminará en una versión futura.
  • --optimize-response: Añade un parámetro fields a cada herramienta para seleccionar qué campos del resultado devolver.
  • --max-tokens=NUMBER: Establece 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...>: Especifica 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

Compatibilidad con múltiples organizaciones

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

Configuración

Configura un par de variables de entorno por organización y establece 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 tu entorno de shell o de un bloque de configuración env de un 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 de múltiples organizaciones, 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 de múltiples organizaciones, 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 el 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 de 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 hay variables de entorno de múltiples organizaciones presentes y falta BACKLOG_DEFAULT_ORG, el servidor falla al iniciarse

Descubrimiento de organizaciones

En el modo de múltiples organizaciones, 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 el 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.