Backlog Remote MCP Server

Un servidor MCP (Model Context Protocol) remoto para Backlog. Desplegable en Cloudflare Workers o AWS.

English | 日本語

Características

• Multi-espacio — sirve varios espacios de Backlog desde un solo servidor

• Guardia de solo lectura — marca un espacio compartido como readOnly para rechazar toda llamada de escritura a la API

• OAuth 2.1 + PKCE — admite el registro dinámico de clientes (DCR), por lo que los clientes MCP se conectan directamente

• Lista de permitidos por correo electrónico — restringe quién puede usar el servidor

• Dos entornos de ejecución — la misma lógica de negocio se ejecuta en Cloudflare o AWS

Related MCP server: backlog-mcp-server

Elección del despliegue

Las herramientas y su comportamiento son idénticos en ambos.

Costo estimado

Nota Estas cifras son solo de referencia. Los cargos reales varían según la región, el uso y los cambios de precios. Usa las calculadoras oficiales para estimaciones reales.

• Precios de Cloudflare Zero Trust

• Precios de Cloudflare Workers

• Calculadora de precios de AWS

Supuestos

Uso personal o un equipo pequeño.

Costos fijos (se cobran incluso en inactividad)

En AWS, el costo fijo es esencialmente solo Secrets Manager, que factura por secreto al mes, se use o no. Cloudflare no tiene costo fijo porque Workers Secrets es gratuito.

Qué se mide

Con el volumen supuesto (~3,000 solicitudes/mes), ambos se mantienen dentro de las asignaciones gratuitas. La API HTTP de API Gateway no tiene nivel gratuito perpetuo, por lo que AWS acumula un pequeño cargo proporcional al número de solicitudes (aproximadamente $1 por millón de solicitudes).

Umbrales que vale la pena conocer

Cloudflare — la línea de 50 usuarios para Zero Trust

Zero Trust (Access) es gratuito hasta 50 usuarios. Más allá de eso, pasas a un plan de pago que se factura por usuario al mes. Este es el costo que escala con el número de empleados.

Cloudflare — límites del plan gratuito de Workers

Este proyecto utiliza Durable Objects respaldados por SQLite, que están disponibles en el plan gratuito de Workers. El plan gratuito limita las solicitudes diarias y otros usos, y superar un límite devuelve errores. Para un uso sostenido, considera Workers de pago (desde $5/mes).

AWS — el nivel gratuito de Lambda es perpetuo

Lambda incluye un nivel gratuito perpetuo de 1M de solicitudes y 400,000 GB-segundos al mes. API Gateway y Secrets Manager no tienen nivel gratuito perpetuo.

AWS — CloudWatch Logs

Los registros se facturan según el volumen de ingesta. Esta plantilla gestiona la retención explícitamente mediante LogRetentionDays (por defecto 30), por lo que los registros no se acumulan indefinidamente.

Resumen

Para equipos pequeños, Cloudflare es más barato y no tiene costo fijo. AWS conlleva el costo fijo de Secrets Manager, pero vale la pena si quieres consolidarte en una infraestructura AWS existente o gobernar el acceso mediante IAM.

Configuración

0. Requisitos previos

Node.js 20 o posterior.

git clone <this-repo>
cd backlog-remote-mcp-server
npm install

Las herramientas adicionales dependen del objetivo de despliegue:

Orden a seguir

1. Claves de API de Backlog y configuración del espacio — compartido por ambas plataformas

2. Elige un proveedor de identidad

   • Google Cloud

   • Microsoft Entra ID

3. Elige un objetivo de despliegue

   • Cloudflare Workers

   • AWS

Si algo sale mal

Las secciones de solución de problemas se encuentran al final de cada guía de despliegue.

• Cloudflare

• AWS

Arquitectura

MCP client (Claude, Kiro, Cursor, ...)
    ↓ Streamable HTTP + OAuth
Runtime (Cloudflare Workers or AWS Lambda)
    ↓ Upstream IdP (Cloudflare Access or Amazon Cognito)
    ↓ Email allowlist check
    ↓ Backlog API key routing
Backlog space A / B / C ...

Estructura de directorios

La lógica de negocio está separada del cableado del entorno de ejecución.

src/
  core/                    Runtime-independent
    backlog-client.ts      Backlog API client (including the readOnly guard)
    tools/                 40 MCP tools
    create-server.ts       MCP server assembly and authorization
  platforms/
    cloudflare/            Cloudflare Workers wiring
    aws/                   AWS Lambda wiring
infra/
  aws/                     SAM template and parameters

src/core depende solo de @modelcontextprotocol/sdk y zod y no hace referencia a ninguna API específica del entorno de ejecución. Añadir una plataforma significa añadir un adaptador en src/platforms/ mientras se comparten las mismas implementaciones de herramientas.

Conexión desde clientes MCP

Claude Desktop / Kiro / Cursor (a través del proxy mcp-remote)

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<MCP_HOSTNAME>/mcp"
      ]
    }
  }
}

En la primera conexión, se abre una ventana del navegador para la autenticación.

MCP Inspector (para pruebas)

npx @modelcontextprotocol/inspector@latest

Introduce https://<MCP_HOSTNAME>/mcp en el inspector y completa el flujo OAuth mediante la configuración de OAuth.

Uso

Especificar un espacio

Todas las herramientas aceptan un parámetro opcional space:

# Use default space
"Show me the issues for PROJECT-KEY"

# Specify a particular space
"List projects in the PERSONAL space"
→ space: "PERSONAL"

Ejemplos

# List configured spaces
"What Backlog spaces are available?" → list_spaces

# List projects
"Show COMPANY_A projects" → get_project_list(space: "COMPANY_A")

# Create an issue
"Create a new bug issue in PROJECT-KEY" → add_issue(...)

# List pull requests
"Show open PRs in repo-name" → get_pull_requests(...)

Herramientas disponibles

add_*, update_* y delete_* son operaciones de escritura. Llamarlas contra un espacio configurado con readOnly: true se rechaza antes de que cualquier solicitud llegue a la API de Backlog. Usa list_spaces para ver el estado readOnly de cada espacio.

Seguridad

• Autenticación: Cloudflare Access → Google / Microsoft Entra ID. Todo el flujo OAuth es gestionado por Cloudflare

• Autorización: ALLOWED_EMAILS proporciona una lista de permitidos por correo electrónico a nivel de aplicación

• Doble verificación: Política de acceso (lado de Cloudflare) + lista de permitidos en la aplicación (lado del Worker)

• Protección de claves de API: Las claves de API de Backlog se almacenan en Cloudflare Secrets y nunca se exponen a los clientes

• PKCE + CSRF: El flujo OAuth está protegido con PKCE (S256) y tokens CSRF

• Consentimiento del cliente: El registro dinámico de clientes está abierto a cualquiera, por lo que la autorización se controla mediante una pantalla de consentimiento que nombra al cliente y su destino de redirección y requiere una aprobación protegida por CSRF. Las aprobaciones se basan en client_id + redirect_uri, por lo que volver a registrarse con un destino de redirección diferente no puede heredar una aprobación anterior

• Guardia de escritura: Los espacios marcados con readOnly: true rechazan toda llamada que no sea GET. La verificación se encuentra en la capa de llamadas a la API de src/core/backlog-client.ts, por lo que no depende de implementaciones individuales de herramientas

• Aislamiento de configuración: Todos los valores específicos del entorno se encuentran en .dev.vars (sin seguimiento). El repositorio contiene solo marcadores de posición

Notas operativas

• ALLOWED_EMAILS es el límite de autorización efectivo para este servidor. No hay ninguna aplicación de Access a nivel de zona delante del Worker

• npm run deploy sobrescribe los secretos de producción con los valores de .dev.vars. Si necesitas valores diferentes localmente y en producción, usa deploy:no-secrets para despliegues rutinarios y envía los secretos explícitamente con secrets:push

• Una clave de API de Backlog conlleva los permisos completos de su propietario. Para espacios que no necesitan escrituras, emite una clave de solo lectura y establece readOnly: true

Desarrollo local

Las ejecuciones locales usan la compilación de Cloudflare Workers (wrangler dev). Como la lógica de negocio vive en src/core, todo lo que verifiques aquí también se aplica al despliegue en AWS.

cp .dev.vars.example .dev.vars   # fill in your values
npm run dev
# Server starts at http://localhost:8788/mcp

wrangler dev emula KV y Durable Objects localmente, por lo que nunca toca recursos reales de Cloudflare.

Verificar la configuración

Ejecuta la verificación completa de OAuth a llamada de herramienta en un solo comando:

npm run check:local

Realiza lo siguiente, abriendo un navegador a mitad de camino para que puedas iniciar sesión:

1. Obtener los metadatos del servidor de autorización

2. Registro dinámico de clientes

3. Aprobar en el navegador → inicio de sesión del IdP

4. Intercambio de tokens con PKCE

5. initialize / tools/list

6. Llamar a get_space y mostrar la respuesta real de Backlog

Si tools/list devuelve solo access_denied, el correo con el que iniciaste sesión no está en la lista de permitidos.

También funciona contra un endpoint desplegado:

npm run check:local -- --base https://your-deployed-host

Ejecución sobre HTTPS

Úsalo cuando el IdP no acepte una URL de redirección http://.

npm run dev:https
# Server starts at https://localhost:8788/mcp (self-signed certificate)

Comprobación de tipos y pruebas

Los tipos están divididos por plataforma, por lo que usar incorrectamente un global de Workers en código de AWS (o viceversa) es un error de tipo.

npm run type-check   # both tsconfig.cloudflare.json and tsconfig.aws.json
npm test             # runs all suites below

Ninguna de ellas llega a servicios externos: DynamoDB y el IdP ascendente están simulados.

Archivos de configuración

Consulta las guías de despliegue para saber cómo rellenarlos.

Licencia

MIT