Backlog MCP Server

Um servidor MCP para interagir com a API do Backlog, uma ferramenta de gerenciamento de projetos e colaboração.

GitHub
14
Experimente este MCPPatrocinado

Documentação

Backlog MCP Server (mcp-backlog-server)

codecov

mcp-backlog-server é um servidor Model Context Protocol (MCP) para interagir com a API do Backlog. Este servidor permite que clientes compatíveis com MCP (como assistentes de IA) utilizem as funcionalidades do Backlog.

Instalação

Usando Homebrew (Recomendado para macOS/Linux)

A maneira mais fácil de instalar é via Homebrew:

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

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

Para atualizar para a versão mais recente:

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

Para desinstalar:

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

Métodos Alternativos de Instalação

Para outras plataformas ou se você preferir não usar Homebrew:

  • Binários pré-compilados: Baixe da página de releases
  • Compilar a partir do código-fonte: Clone o repositório e execute cargo build --release

Exemplo de Configuração para Cliente MCP

Claude Desktop

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

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

Cline

Adicione o seguinte à sua configuração MCP do Cline:

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

Gemini CLI

~/.gemini/settings.json:

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

Nota: O nome do domínio deve ser: backlog.com, backlog.jp ou backlogtool.com

Ferramentas Disponíveis

As seguintes ferramentas estão agrupadas por seus respectivos módulos:

Resumo das Ferramentas

Com a configuração padrão, você tem acesso a 39 ferramentas para automação do Backlog:

  • Documentos (5 ferramentas): Visualizar árvores de documentos, obter detalhes, baixar anexos, adicionar documentos, excluir documentos
  • Git/Pull Requests (8 ferramentas): Gerenciar repositórios, PRs, comentários e anexos
  • Issues (15 ferramentas): Visualizar, criar, atualizar issues, gerenciar comentários, anexos, arquivos compartilhados, issues relacionadas e prioridades
  • Projetos (3 ferramentas): Obter status do projeto, tipos de issue e definições de campos personalizados
  • Arquivos Compartilhados (2 ferramentas): Navegar e baixar arquivos compartilhados do projeto
  • Usuários (1 ferramenta): Listar usuários do espaço
  • Wikis (5 ferramentas): Gerenciar páginas wiki, anexos e atualizações de conteúdo

O servidor inclui tanto operações de leitura para coleta de informações quanto operações de escrita para realizar ações.

Nota: Os nomes das ferramentas seguem um padrão category_resource_action (por exemplo, issue_details_get, wiki_update) para permitir filtragem por categoria com --allowedTools (por exemplo, claude --allowedTools "mcp__backlog__issue_*").

Ferramentas de Documento

  • document_details_get: Recupera detalhes de um documento específico do Backlog
  • document_attachment_download: Baixa um anexo de documento
  • document_tree_get: Obtém a árvore de documentos de um projeto especificado
  • document_add: Adiciona um novo documento a um projeto do Backlog
  • document_delete: Exclui um documento do Backlog

Ferramentas Git

  • git_repository_list_get: Obtém uma lista de repositórios Git de um projeto especificado
  • git_repository_details_get: Obtém detalhes de um repositório Git específico
  • git_pr_list_get: Obtém uma lista de pull requests de um repositório especificado
  • git_pr_details_get: Obtém detalhes de um pull request específico
  • git_pr_attachment_list_get: Obtém uma lista de anexos de um pull request específico
  • git_pr_comment_list_get: Obtém uma lista de comentários de um pull request específico
  • git_pr_attachment_download: Baixa um anexo de pull request
  • git_pr_comment_add: Adiciona um comentário a um pull request específico

Ferramentas de Issue

  • issue_details_get: Recupera detalhes de uma issue específica do Backlog
  • issue_milestone_list_get: Recupera uma lista de versões (marcos) de um projeto especificado
  • issue_list_by_milestone_get: Recupera uma lista de issues associadas a um marco especificado
  • issue_update: Atualiza uma issue do Backlog incluindo resumo, descrição e campos personalizados
  • issue_comment_list_get: Obtém comentários de uma issue específica
  • issue_attachment_list_get: Obtém uma lista de anexos de uma issue especificada
  • issue_attachment_download: Baixa um anexo de issue
  • issue_shared_file_list_get: Obtém uma lista de arquivos compartilhados vinculados a uma issue especificada
  • issue_related_issue_list_get: Obtém issues relacionadas de uma issue especificada (issues ocultas são relatadas como omittedCount)
  • issue_related_issue_add: Adiciona uma issue relacionada a uma issue do Backlog
  • issue_related_issue_remove: Remove uma issue relacionada de uma issue do Backlog
  • issue_comment_update: Atualiza um comentário existente em uma issue do Backlog
  • issue_add: Cria uma nova issue em um projeto do Backlog com suporte a campos personalizados
  • issue_comment_add: Adiciona um comentário a uma issue específica
  • issue_priority_list_get: Obtém uma lista de tipos de prioridade disponíveis no espaço

Ferramentas de Projeto

  • project_status_list_get: Obtém uma lista de status de um projeto especificado
  • project_issue_type_list_get: Obtém uma lista de tipos de issue de um projeto especificado
  • project_custom_field_list_get: Obtém uma lista de campos personalizados definidos para um projeto especificado

Ferramentas de Arquivo Compartilhado

  • file_shared_list_get: Obtém uma lista de arquivos compartilhados de um diretório de projeto especificado
  • file_shared_download: Baixa um arquivo compartilhado

Ferramentas de Usuário

  • user_list_get: Obtém uma lista de usuários no espaço

Ferramentas de Wiki

  • wiki_list_get: Obtém uma lista de páginas wiki
  • wiki_details_get: Obtém informações detalhadas sobre uma página wiki específica
  • wiki_attachment_list_get: Obtém uma lista de anexos de uma página wiki especificada
  • wiki_attachment_download: Baixa um anexo de uma página wiki
  • wiki_update: Atualiza uma página wiki

Recursos de Download de Arquivos

Todas as ferramentas de download de arquivos (document_attachment_download, issue_attachment_download, git_pr_attachment_download, wiki_attachment_download e file_shared_download) suportam detecção e manipulação de formato:

Detecção de Formato

  • Imagens: Arquivos com tipo de conteúdo image/* são detectados e retornados como imagens codificadas em base64 via rmcp::model::ContentBlock::image
  • Texto: Arquivos com tipos de conteúdo baseados em texto (text/*, application/json, application/xml, etc.) ou arquivos que contêm texto UTF-8 válido são retornados como texto simples via rmcp::model::ContentBlock::text
  • Bytes brutos: Todos os outros arquivos são retornados como objetos JSON com conteúdo codificado em base64, nome do arquivo e tipo MIME

Substituição Manual de Formato

Você pode especificar explicitamente o formato usando o parâmetro opcional format:

  • "image": Força o tratamento como imagem (valida o tipo de conteúdo)
  • "text": Força o tratamento como texto (valida a codificação UTF-8)
  • "raw": Força o tratamento como bytes brutos (sem validação)

Detecção de Tipo de Conteúdo

O sistema usa múltiplas estratégias para determinar se um arquivo é texto:

  • Análise do cabeçalho Content-Type
  • Verificação de validade UTF-8
  • Análise de composição de caracteres (caracteres gráficos, espaços em branco e caracteres UTF-8 válidos)

Como Compilar

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

Flags de Recursos

O servidor MCP suporta múltiplas flags de recursos para habilitar diferentes operações de escrita:

  • issue_writable (habilitado por padrão)

    • Habilita: ferramentas issue_update, issue_comment_update, issue_add e issue_comment_add
    • Permite que agentes de IA criem issues, modifiquem conteúdo de issues e gerenciem comentários

  • git_writable (habilitado por padrão)

    • Habilita: ferramenta git_pr_comment_add
    • Permite que agentes de IA adicionem comentários a pull requests

  • wiki_writable (habilitado por padrão)

    • Habilita: ferramenta wiki_update
    • Permite que agentes de IA atualizem conteúdo de páginas wiki, nomes e configurações de notificação

  • document_writable (habilitado por padrão)

    • Habilita: ferramentas document_add e document_delete
    • Permite que agentes de IA criem e excluam documentos

Configuração de Compilação

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

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

Configuração

Para executar este servidor, as seguintes variáveis de ambiente devem ser definidas:

  • BACKLOG_BASE_URL: A URL do seu espaço Backlog (por exemplo, https://your-space.backlog.com)
  • BACKLOG_API_KEY: Sua chave de API do Backlog. Você pode emitir uma na página de configurações pessoais no Backlog.

Variáveis de ambiente opcionais:

  • BACKLOG_PROJECTS: Lista separada por vírgulas de chaves de projeto permitidas (por exemplo, MFP,DEMO,TEST). Quando definida, o servidor permitirá acesso apenas aos projetos especificados. Se não definida, todos os projetos acessíveis com a chave de API estarão disponíveis.
  • BACKLOG_PREFIX: Prefixo personalizado para nomes de ferramentas (padrão: backlog_). Por exemplo, definir BACKLOG_PREFIX="" remove o prefixo, tornando as ferramentas acessíveis como issue_details_get em vez de backlog_issue_details_get. Definir BACKLOG_PREFIX="my_" altera as ferramentas para my_issue_details_get.

Espera-se que essas variáveis de ambiente sejam passadas pelo sistema cliente MCP ao iniciar o servidor.

Executar (para testes locais)

Após definir as variáveis de ambiente, você pode executar o servidor diretamente com o seguinte comando:

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