Backlog MCP Server

Interaja com a API do Backlog para gerenciar projetos, issues, wikis, repositórios git e mais.

GitHub
233
Experimente este MCPPatrocinado

Documentação

Backlog MCP Server

MCP Toplist MIT License Build Last Commit

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

Um servidor Model Context Protocol (MCP) para interagir com a API do Backlog. Este servidor fornece ferramentas para gerenciar projetos, issues, páginas de wiki e muito mais no Backlog por meio de agentes de IA como Claude Desktop / Cline / Cursor, entre outros.

Recursos

  • Ferramentas de projeto (criar, ler, atualizar, excluir)
  • Rastreamento de issues e comentários (criar, atualizar, excluir, listar)
  • Gerenciamento de versões/marcos (criar, ler, atualizar, excluir)
  • Suporte a páginas de wiki
  • Ferramentas de repositório Git e pull requests
  • Ferramentas de notificação
  • Seleção de campos para respostas otimizadas
  • Limite de tokens para respostas grandes

Primeiros Passos

Requisitos

  • Docker
  • Uma conta Backlog com acesso à API
  • Chave de API da sua conta Backlog

Opção 1: Instalação via Docker

A maneira mais fácil de usar este servidor MCP é por meio das configurações do MCP:

  1. Abra as configurações do MCP
  2. Navegue até a seção de configuração do MCP
  3. Adicione a seguinte configuração:
{
  "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"
      }
    }
  }
}

Substitua your-domain.backlog.com pelo seu domínio do Backlog e your-api-key pela sua chave de API do Backlog.

✅ Se você não puder usar --pull always, poderá atualizar manualmente a imagem usando:

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

Opção 2: Instalação via npx

Você também pode executar o servidor diretamente usando npx sem clonar o repositório. Esta é uma maneira conveniente de executar o servidor sem uma instalação completa.

  1. Abra as configurações do MCP
  2. Navegue até a seção de configuração do MCP
  3. Adicione a seguinte configuração:
{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": ["backlog-mcp-server"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

Substitua your-domain.backlog.com pelo seu domínio do Backlog e your-api-key pela sua chave de API do Backlog.

Opção 3: Configuração Manual (Node.js)

  1. Clone e instale:

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

  2. Crie .env a partir do modelo e defina as variáveis necessárias:

cp .env.example .env

Defina os seguintes valores em .env:

  • BACKLOG_DOMAIN=your-domain.backlog.com
  • BACKLOG_API_KEY=your-api-key
  1. Execute localmente:
pnpm run dev
  1. Configure seu json para usar 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 padrão, o servidor usa stdio. Para executar o transporte MCP Streamable HTTP (JSON-RPC sobre HTTP, mesmas ferramentas do stdio), inicie com --transport http ou defina MCP_TRANSPORT=http.

pnpm run build
MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js
  • Endpoint: POST (e GET para streams iniciados pelo servidor) em http://<host>:<port><path> (caminho padrão /mcp).
  • Protocolo: MCP 2026-07-28. O protocolo não tem estado: não há handshake initialize nem cabeçalho mcp-session-id. Os clientes enviam seus metadados em _meta em cada solicitação e descobrem capacidades via server/discover. O Streamable HTTP também exige o cabeçalho Mcp-Method (e Mcp-Name em tools/call).
  • Compatibilidade reversa: Clientes em 2025-11-25 e versões anteriores ainda são atendidos no mesmo endpoint, sem estado. Como nenhuma sessão é mantida, as operações de sessão de 2025 (GET / DELETE com um mcp-session-id) respondem 405.
  • Segurança: O bind padrão é 127.0.0.1. Em um bind de loopback simples, Host e Origin são ambos validados contra o conjunto de localhost (proteção contra rebinding de DNS). Atrás de um proxy reverso, defina --http-allowed-hosts para o hostname público; isso desativa o padrão de localhost Origin, já que o Origin de um cliente de navegador é seu próprio site e nunca o hostname deste servidor. Adicione --http-allowed-origins para restringir quais origens de clientes podem acessar o servidor. Não exponha a porta HTTP a redes não confiáveis sem autenticação e TLS; isso permite o uso completo da sua chave de API do Backlog por meio das ferramentas MCP.

Variáveis de ambiente (flags de CLI têm precedência quando ambas estão definidas):

VariávelDescrição
MCP_TRANSPORTstdio (padrão) ou http
MCP_HTTP_HOSTEndereço de bind (padrão 127.0.0.1)
MCP_HTTP_PORTPorta (padrão 3333)
MCP_HTTP_PATHCaminho da URL (padrão /mcp)
MCP_HTTP_JSON_RESPONSEtrue para preferir respostas JSON em vez de SSE (aplica-se apenas a clientes 2026-07-28)
MCP_HTTP_ALLOWED_HOSTSHostnames Host permitidos separados por vírgula (independentes de porta). Obrigatório ao fazer bind em 0.0.0.0; também é a alternativa para um bind de loopback atrás de um proxy (proteção contra rebinding de DNS)
MCP_HTTP_ALLOWED_ORIGINSHostnames Origin permitidos separados por vírgula para clientes baseados em navegador. Padrão: conjunto de localhost em um bind de loopback simples, e sem verificação de Origin caso contrário

Autenticação OAuth 2.0 (MCP Remoto)

Ao expor o servidor MCP em uma rede, você pode habilitar a autenticação OAuth 2.0 para que cada usuário autentique com sua própria conta Backlog em vez de compartilhar uma única chave de API.

O servidor implementa o Fluxo de Autorização de Terceiros MCP atuando tanto como servidor de autorização OAuth (para clientes MCP) quanto como cliente OAuth (para o Backlog).

Pré-requisitos

  1. Registre um aplicativo OAuth no seu espaço Backlog:

    • Vá para seu espaço Backlog → Configurações Pessoais → Registrar Aplicativo
    • Defina a URI de Redirecionamento para <MCP_SERVER_BASE_URL>/callback (ex.: https://mcp.example.com/callback)
    • Anote o Client ID e o Client Secret

  2. Defina as seguintes variáveis de ambiente (além de BACKLOG_DOMAIN):

VariávelDescrição
BACKLOG_OAUTH_CLIENT_IDClient ID OAuth do seu aplicativo Backlog
BACKLOG_OAUTH_CLIENT_SECRETClient Secret OAuth do seu aplicativo Backlog
MCP_SERVER_BASE_URLURL pública do seu servidor MCP (ex.: https://mcp.example.com)

Observação: BACKLOG_API_KEY não é necessário quando o OAuth está habilitado — cada usuário autentica com sua própria conta Backlog.

Exemplo

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 é necessário na prática ao fazer bind em 0.0.0.0: sem ele, não há proteção contra rebinding de DNS, e o servidor registra um aviso na inicialização.

O servidor expõe automaticamente os seguintes endpoints OAuth quando o OAuth está habilitado:

EndpointDescrição
GET /.well-known/oauth-authorization-serverMetadados do Servidor de Autorização OAuth (RFC 8414)
GET /.well-known/oauth-protected-resource/mcpMetadados do Recurso Protegido OAuth (RFC 9728)
POST /registerRegistro Dinâmico de Clientes (RFC 7591)
GET /authorizeEndpoint de autorização (redireciona para o OAuth do Backlog)
GET /callbackCallback OAuth do Backlog
POST /tokenEndpoint de token (código de autorização e token de atualização)

Clientes MCP que suportam a especificação de autorização MCP usarão esses endpoints automaticamente.

POST /register restringe quais URIs de redirecionamento um cliente pode registrar. Uma URI de loopback (http://localhost, http://127.0.0.1, http://[::1]) é como um aplicativo executado na máquina do usuário recebe o código de autorização, e é aceita de um cliente que declare "application_type": "native" — ou, quando o campo estiver ausente, de um cliente cujas URIs de redirecionamento são todas de loopback. Um cliente que declare "application_type": "web", ou que misture uma URI https: remota com uma de loopback sem se declarar, é rejeitado com invalid_client_metadata.

Limitações:

  • O modo OAuth atualmente suporta uma única organização Backlog. Não é compatível com a configuração de múltiplas organizações.
  • Registros de clientes e tokens são armazenados em memória e serão perdidos ao reiniciar o servidor.

Configuração de Ferramentas

Você pode habilitar ou desabilitar seletivamente conjuntos de ferramentas específicos usando o flag de linha de comando --enable-toolsets ou a variável de ambiente ENABLE_TOOLSETS. Isso permite melhor controle sobre quais ferramentas estão disponíveis para o agente de IA e ajuda a reduzir o tamanho do contexto.

Conjuntos de Ferramentas Disponíveis

Os seguintes conjuntos de ferramentas estão disponíveis (habilitados por padrão quando "all" é usado):

Conjunto de FerramentasDescrição
spaceFerramentas para gerenciar configurações do espaço Backlog e informações gerais
projectFerramentas para gerenciar projetos, categorias, campos personalizados e tipos de issue
issueFerramentas para gerenciar issues e seus comentários, versões e marcos
wikiFerramentas para gerenciar páginas de wiki
gitFerramentas para gerenciar repositórios Git e pull requests
notificationsFerramentas para gerenciar notificações de usuários
documentFerramentas para visualizar documentos e árvores de documentos

Especificando Conjuntos de Ferramentas

Você pode controlar a ativação dos conjuntos de ferramentas das seguintes maneiras:

Usando via CLI:

--enable-toolsets space,project,issue

Ou via variável de ambiente:

ENABLE_TOOLSETS="space,project,issue"

Se all for especificado, todos os conjuntos de ferramentas disponíveis serão habilitados. Este também é o comportamento padrão.

Usar conjuntos de ferramentas seletivos pode ser útil se a lista de ferramentas for grande demais para seu agente de IA ou se certas ferramentas estiverem causando problemas de desempenho. Nesses casos, desabilitar conjuntos de ferramentas não utilizados pode melhorar a estabilidade.

🧩 Dica: O conjunto de ferramentas project é altamente recomendado, pois muitas outras ferramentas dependem dos dados do projeto como ponto de entrada.

Ferramentas Disponíveis

Conjunto de Ferramentas: space

Ferramentas para gerenciar configurações do espaço Backlog e informações gerais.

  • get_space: Retorna informações sobre o espaço Backlog.
  • get_users: Retorna a lista de usuários no espaço Backlog.
  • get_myself: Retorna informações sobre o usuário autenticado.

Conjunto de Ferramentas: project

Ferramentas para gerenciar projetos, categorias, campos personalizados e tipos de issue.

  • get_project_list: Retorna a lista de projetos.
  • add_project: Cria um novo projeto.
  • get_project: Retorna informações sobre um projeto específico.
  • get_project_users: Retorna a lista de usuários em um projeto específico.
  • update_project: Atualiza um projeto existente.

Conjunto de Ferramentas: issue

Ferramentas para gerenciar issues, seus comentários e itens relacionados, como prioridades, categorias, campos personalizados, tipos de issue, resoluções e listas de acompanhamento.

  • get_issue: Retorna informações sobre uma issue específica.
  • get_issue_attachment: Baixa um anexo de uma issue. Retorna como imagem ou conteúdo de recurso incorporado, ou como base64 com format: "base64".
  • get_issues: Retorna uma lista de issues.
  • count_issues: Retorna a contagem de issues.
  • add_issue: Cria uma nova issue no projeto especificado.
  • update_issue: Atualiza uma issue existente.
  • delete_issue: Exclui uma issue.
  • get_issue_comments: Retorna uma lista de comentários de uma issue.
  • add_issue_comment: Adiciona um comentário a uma issue.
  • update_issue_comment: Atualiza um comentário em uma issue.
  • get_related_issues: Retorna uma lista de issues relacionadas a uma issue específica.
  • add_related_issue: Relaciona uma issue a outra issue.
  • remove_related_issue: Remove a relação entre uma issue e uma issue relacionada.
  • get_priorities: Retorna uma lista de prioridades.
  • get_categories: Retorna uma lista de categorias de um projeto.
  • add_category: Cria uma nova categoria para um projeto.
  • get_custom_fields: Retorna uma lista de campos personalizados de um projeto.
  • get_issue_types: Retorna uma lista de tipos de issue de um projeto.
  • get_resolutions: Retorna uma lista de resoluções de issue.
  • get_watching_list_items: Retorna uma lista de itens de acompanhamento de um usuário.
  • get_watching_list_count: Retorna a contagem de itens de acompanhamento de um usuário.
  • add_watching: Adiciona um novo acompanhamento a uma issue.
  • update_watching: Atualiza uma nota de acompanhamento existente.
  • delete_watching: Exclui um acompanhamento de uma issue.
  • mark_watching_as_read: Marca um acompanhamento como lido.
  • get_version_milestone_list: Retorna uma lista de marcos de versão de um projeto.
  • add_version_milestone: Cria um novo marco de versão para um projeto.
  • update_version_milestone: Atualiza um marco de versão existente.
  • delete_version_milestone: Exclui um marco de versão.

Conjunto de ferramentas: wiki

Ferramentas para gerenciar páginas wiki.

  • get_wiki_pages: Retorna uma lista de páginas Wiki.
  • get_wikis_count: Retorna a contagem de páginas wiki em um projeto.
  • get_wiki: Retorna informações sobre uma página wiki específica.
  • add_wiki: Cria uma nova página wiki.

Conjunto de ferramentas: git

Ferramentas para gerenciar repositórios Git e pull requests.

  • get_git_repositories: Retorna uma lista de repositórios Git de um projeto.
  • get_git_repository: Retorna informações sobre um repositório Git específico.
  • get_pull_requests: Retorna uma lista de pull requests de um repositório.
  • get_pull_requests_count: Retorna a contagem de pull requests de um repositório.
  • get_pull_request: Retorna informações sobre um pull request específico.
  • add_pull_request: Cria um novo pull request.
  • update_pull_request: Atualiza um pull request existente.
  • get_pull_request_comments: Retorna uma lista de comentários de um pull request.
  • add_pull_request_comment: Adiciona um comentário a um pull request.
  • update_pull_request_comment: Atualiza um comentário em um pull request.

Conjunto de ferramentas: notifications

Ferramentas para gerenciar notificações de usuário.

  • get_notifications: Retorna uma lista de notificações.
  • get_notifications_count: Retorna a contagem de notificações.
  • reset_unread_notification_count: Redefine a contagem de notificações não lidas.
  • mark_notification_as_read: Marca uma notificação como lida.

Conjunto de ferramentas: document

Ferramentas para gerenciar documentos e árvores de documentos em projetos Backlog.

  • get_document_tree: Retorna a árvore hierárquica de documentos de um projeto, incluindo pastas e ne
  • get_documents: Retorna uma lista plana de documentos em um projeto ou pasta.
  • get_document: Retorna informações detalhadas sobre um documento específico, incluindo metadados, conteúdo e

Exemplos de uso

Depois que o servidor MCP estiver configurado em agentes de IA, você pode usar as ferramentas diretamente em suas conversas. Aqui estão alguns exemplos:

  • Listando Projetos
Could you list all my Backlog projects?
  • Criando uma Nova Issue
Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"
  • Obtendo Detalhes do Projeto
Show me the details of the PROJECT-KEY project
  • Trabalhando com Repositórios Git
List all Git repositories in the PROJECT-KEY project
  • Gerenciando Pull Requests
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
  • Itens de Acompanhamento
Show me all items I'm watching

Substituindo Descrições de Ferramentas

Você pode substituir as descrições das ferramentas criando um arquivo .backlog-mcp-serverrc.json no seu diretório pessoal.

Quase todas essas strings são as descrições de ferramentas e parâmetros que o modelo lê ao decidir qual ferramenta chamar e como preencher seus argumentos. Portanto, substituí-las é uma forma de orientar a seleção de ferramentas — por exemplo, para diferenciar duas ferramentas semelhantes ou adicionar uma regra que sua equipe segue — em vez de uma forma de alterar o idioma das respostas que você obtém. O modelo responde no idioma em que você perguntar, independentemente do idioma em que essas descrições estão escritas.

Um pequeno número de chaves são mensagens de erro de validação (por exemplo, PROJECT_ID_OR_KEY_REQUIRED). Elas são retornadas no resultado da ferramenta quando uma chamada é rejeitada, então podem chegar até você por meio da resposta do modelo.

O arquivo deve conter um objeto JSON com os nomes das ferramentas como chaves e as novas descrições como valores.
Por exemplo:

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

Quando o servidor inicia, ele determina a descrição final de cada ferramenta com base na seguinte prioridade:

  1. Variáveis de ambiente (por exemplo, BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION)
  2. Entradas em .backlog-mcp-serverrc.json - Formatos de arquivo de configuração suportados: .json, .yaml, .yml
  3. Padrões integrados

Valores vazios ou não-string são ignorados em todos os níveis, e o padrão integrado é usado em seu lugar.

Configuração de exemplo:

{
  "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"
      }
    }
  }
}

Exportando Descrições Atuais

Você pode exportar as descrições atuais (incluindo quaisquer substituições) executando o binário com a flag --export-descriptions. Esta flag era anteriormente chamada de --export-translations; o nome antigo ainda funciona, mas imprime um aviso de depreciação e será removido em uma versão futura.

Isso imprime cada chave que é resolvida enquanto a lista de ferramentas é construída, com seu valor atual, incluindo quaisquer personalizações que você tenha feito. Isso cobre todas as descrições de ferramentas e parâmetros, e é a forma prática de descobrir os nomes das chaves.

Isso não cobre as mensagens de erro de validação, porque essas chaves só são resolvidas quando uma chamada é realmente rejeitada. Elas ainda podem ser substituídas pelas mesmas regras; você só precisa lê-las do código-fonte.

Exemplo:

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

ou

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

Usando Variáveis de Ambiente

Alternativamente, você pode substituir as descrições das ferramentas por meio de variáveis de ambiente.

Os nomes das variáveis de ambiente são baseados nas chaves das ferramentas, prefixados com BACKLOGMCP e escritos em maiúsculas.

Exemplo: Para substituir o 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"
      }
    }
  }
}

O servidor carrega o arquivo de configuração de forma síncrona na inicialização.

As variáveis de ambiente sempre têm precedência sobre o arquivo de configuração.

Recursos Avançados

Prefixo de Nome de Ferramenta

Adicione um prefixo aos nomes das ferramentas com:

--prefix backlog_

ou por meio de variável de ambiente:

PREFIX="backlog_"

Isso é especialmente útil se você estiver usando vários servidores MCP ou ferramentas no mesmo ambiente e quiser evitar colisões de nomes. Por exemplo, get_project pode se tornar backlog_get_project para distingui-lo de ferramentas com nomes semelhantes fornecidas por outros serviços.

Otimização de Resposta e Limites de Token

Seleção de Campos

--optimize-response

Ou variável de ambiente:

OPTIMIZE_RESPONSE=1

Ferramentas que retornam uma lista aceitam então um parâmetro opcional fields: uma lista de nomes de campos de nível superior do resultado da própria ferramenta, publicada como um enum para que um nome que a ferramenta não possui seja rejeitado em vez de ignorado. Ferramentas que retornam um único registro não o recebem — o parâmetro custa esquema em cada sessão, e um registro quase não tem nada para reduzir.

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

Omitir fields retorna o resultado completo. A seleção tem um nível de profundidade: nomear um campo de objeto ou array retorna-o por completo.

Benefícios:

  • Reduzir o tamanho da resposta solicitando apenas os campos necessários
  • Focar em pontos de dados específicos
  • Melhorar o desempenho para respostas grandes

Limitação de Token

Respostas grandes são automaticamente limitadas para evitar exceder os limites de token:

  • Limite padrão: 50.000 tokens
  • Configurável por meio da variável de ambiente MAX_TOKENS
  • Respostas que excedem o limite são truncadas com uma mensagem

Você pode alterar isso usando:

MAX_TOKENS=10000

Se uma resposta exceder o limite, ela será truncada com um aviso.

Nota: Esta é uma mitigação de melhor esforço, não uma garantia de aplicação.

Registro de Logs

O servidor registra logs em stderr (o stdout carrega o fluxo JSON-RPC no transporte stdio).

VariávelDescrição
LOG_LEVELfatal, error, warn, info, debug, trace ou silent. O padrão é error quando NODE_ENV é production — que também é o padrão quando NODE_ENV não está definido — e debug caso contrário. Um valor não reconhecido é relatado e o padrão é usado.

NODE_ENV ainda seleciona o formato de saída: qualquer valor diferente de production alterna para saída pino-pretty legível por humanos quando esse pacote está disponível. Use LOG_LEVEL, não NODE_ENV, para alterar quanto é registrado, para que uma implantação mantenha JSON estruturado:

pino-pretty é uma dependência de desenvolvimento, portanto nem o pacote npm publicado nem a imagem de contêiner carregam uma cópia. Nesses casos, os logs são JSON estruturado, independentemente do que NODE_ENV diz, e LOG_LEVEL é a única configuração que altera a saída.

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

Exemplo Completo de Configuração Personalizada

Esta seção demonstra configuração avançada usando múltiplas variáveis de ambiente. Esses são recursos experimentais e podem não ser suportados em todos os clientes MCP. Isso não faz parte da especificação padrão do MCP e deve ser usado com cautela.

{
  "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"
      }
    }
  }
}

Desenvolvimento

Executando Testes

pnpm test

Adicionando Novas Ferramentas

  1. Crie um novo arquivo em src/tools/ seguindo o padrão das ferramentas existentes
  2. Crie um arquivo de teste correspondente
  3. Adicione a nova ferramenta a src/tools/tools.ts
  4. Compile e teste suas alterações

Opções de Linha de Comando

O servidor suporta várias opções de linha de comando:

  • --transport stdio|http: Transporte MCP (padrão: stdio). Use http para Streamable HTTP.
  • --http-host, --http-port, --http-path: Endereço de bind HTTP, porta e caminho (padrões: 127.0.0.1, 3333, /mcp).
  • --http-json-response: Prefira respostas JSON em vez de SSE. Aplica-se apenas a clientes 2026-07-28; o caminho 2025-11-25 compatível com versões anteriores é servido com a modelagem de resposta padrão do SDK.
  • --http-allowed-hosts: Lista de hostnames Host permitidos separados por vírgula (independente de porta). Necessário ao fazer bind em todas as interfaces, ou em um bind de loopback atrás de um proxy reverso.
  • --http-allowed-origins: Lista de hostnames Origin permitidos separados por vírgula para clientes baseados em navegador. O padrão é o conjunto localhost em um bind de loopback simples, e nenhuma verificação de Origin caso contrário.
  • --export-descriptions: Exporta as chaves e valores de descrição resolvidos ao construir a lista de ferramentas. Anteriormente chamado de --export-translations; essa grafia ainda funciona como alias obsoleto e será removida em uma versão futura.
  • --optimize-response: Adiciona um parâmetro fields a cada ferramenta para selecionar quais campos de resultado retornar.
  • --max-tokens=NUMBER: Define o limite máximo de tokens para respostas.
  • --prefix=STRING: Prefixo de string opcional para adicionar a todos os nomes de ferramentas (padrão: "").
  • --enable-toolsets <toolsets...>: Especifica quais conjuntos de ferramentas habilitar (separados por vírgula ou múltiplos argumentos). O padrão é "all". Exemplo: --enable-toolsets space,project ou --enable-toolsets issue --enable-toolsets git Conjuntos de ferramentas disponíveis: space, project, issue, wiki, git, notifications.

Exemplo:

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

Exemplo HTTP:

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

Suporte a Múltiplas Organizações

Este servidor pode ser configurado para acessar múltiplas organizações do Backlog a partir de uma única instância do servidor MCP.

Configuração

Configure um par de variáveis de ambiente por organização e defina uma organização padrão:

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

Isso funciona tanto se as variáveis vierem de um .env local, do ambiente do seu shell ou de um bloco de configuração env do cliente MCP.

Exemplo de configuração 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"
  }
}

Se nenhuma variável de ambiente de múltiplas organizações for definida, o servidor volta à configuração existente de organização única:

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

Uso das Ferramentas

Quando as variáveis de ambiente de múltiplas organizações estão configuradas, todas as ferramentas normais aceitam um campo de entrada opcional organization. Quando fornecido, a chamada da ferramenta é roteada para essa organização do Backlog.

No modo de organização única, o campo não é publicado, pois haveria apenas uma organização para rotear. Omiti-lo mantém cerca de 8 KB do esquema de ferramentas fora de cada resposta tools/list.

Exemplos:

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

Se organization for omitido:

  • a organização nomeada por BACKLOG_DEFAULT_ORG é usada
  • se as variáveis de ambiente de múltiplas organizações estiverem presentes e BACKLOG_DEFAULT_ORG estiver ausente, o servidor falha na inicialização

Descoberta de Organizações

No modo de múltiplas organizações, o servidor fornece uma ferramenta list_organizations que retorna os nomes das organizações configuradas, seus domínios e qual é a padrão. Ela não é registrada no modo de organização única.

Exemplo de resposta:

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

Notas

  • Para o modo de múltiplas organizações, cada organização deve definir tanto BACKLOG_ORG_<NAME>_DOMAIN quanto BACKLOG_ORG_<NAME>_API_KEY.
  • A parte <NAME> é o nome da organização exposto por meio da entrada da ferramenta organization e list_organizations.

Licença

Este projeto está licenciado sob a Licença MIT.

Por favor, observe: Esta ferramenta é fornecida sob a Licença MIT sem qualquer garantia ou suporte oficial.
Use por sua conta e risco após revisar o conteúdo e determinar sua adequação às suas necessidades.
Se encontrar algum problema, reporte-o por meio das Issues do GitHub.