Configuração

Código Aberto — O GitScrum MCP Server é código aberto sob a licença MIT. Disponível no npm e no GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor e qualquer cliente compatível com MCP têm acesso operacional completo à sua stack de gerenciamento de projetos.

Este guia cobre a configuração detalhada para cada cliente MCP suportado, variáveis de ambiente, uso com Docker, argumentos personalizados e etapas de verificação. Se você seguiu o Início Rápido e precisa de opções de configuração mais avançadas, esta é sua referência.

Claude Desktop

O Claude Desktop lê sua configuração MCP de um arquivo JSON no seu sistema de arquivos local.

Localização do arquivo de configuração

Se o arquivo não existir, crie-o manualmente. Certifique-se de que os diretórios pai existem.

Configuração mínima

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Isso instrui o Claude Desktop a iniciar o GitScrum MCP Server usando npx, que baixa e executa a versão mais recente automaticamente.

Adicionando à configuração existente

Se você já tem outros servidores MCP configurados, adicione gitscrum como uma nova entrada no objeto mcpServers:

{
  "mcpServers": {
    "other-server": {
      "command": "other-command",
      "args": ["other-args"]
    },
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Usando uma instalação global

Se você instalou o servidor globalmente com npm install -g @gitscrum-studio/mcp-server, referencie o binário diretamente:

{
  "mcpServers": {
    "gitscrum": {
      "command": "gitscrum-mcp-server"
    }
  }
}

Com variáveis de ambiente

Para passar variáveis de ambiente ao processo do servidor MCP:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"],
      "env": {
        "GITSCRUM_API_URL": "https://services.gitscrum.com"
      }
    }
  }
}

Aplicando alterações

Reinicie o Claude Desktop após editar o arquivo de configuração. O Claude Desktop lê a configuração apenas na inicialização. Após reiniciar, as ferramentas GitScrum aparecem automaticamente na listagem de ferramentas do Claude.

VS Code com GitHub Copilot

O GitHub Copilot lê configurações de servidores MCP de um arquivo JSON no seu workspace ou configurações de usuário.

Configuração por workspace (por projeto)

Crie ou edite .vscode/mcp.json no diretório raiz do seu projeto:

{
  "servers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Esta configuração se aplica apenas ao workspace atual. Membros da equipe que abrirem o mesmo projeto também terão o GitScrum MCP Server configurado automaticamente se o arquivo estiver no controle de versão.

Configuração no nível do usuário (global)

Para tornar o GitScrum MCP Server disponível em todos os workspaces do VS Code, adicione-o nas configurações de usuário do VS Code. Abra as configurações (Ctrl+, / Cmd+,), pesquise por "mcp" e adicione a configuração do servidor. Alternativamente, edite settings.json:

{
  "mcp": {
    "servers": {
      "gitscrum": {
        "command": "npx",
        "args": ["-y", "@gitscrum-studio/mcp-server"]
      }
    }
  }
}

Verificação

Após salvar a configuração:

1. Abra o painel do GitHub Copilot Chat
2. Digite: "Listar meus workspaces do GitScrum"
3. O Copilot deve invocar o servidor MCP e retornar os dados do seu workspace

Se as ferramentas não aparecerem, recarregue a janela: Ctrl+Shift+P → "Developer: Reload Window".

Cursor

O Cursor suporta servidores MCP através do seu sistema de configuração.

Localização do arquivo de configuração

Configuração

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Via interface de Configurações do Cursor

Alternativamente, navegue até Cursor Settings → MCP e adicione um novo servidor:

• Name: gitscrum
• Command: npx
• Arguments: -y @gitscrum-studio/mcp-server

Aplicando alterações

Reinicie o Cursor após editar a configuração. As ferramentas GitScrum aparecem na listagem de ferramentas no painel de IA do Cursor.

Windsurf

O Windsurf lê configuração MCP do seu arquivo de configurações.

Configuração

Adicione à configuração MCP do Windsurf:

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Reinicie o Windsurf após salvar para ativar o servidor.

Continue (VS Code / JetBrains)

O Continue suporta servidores MCP através do seu arquivo de configuração.

Arquivo de configuração

Edite ~/.continue/config.json e adicione o servidor GitScrum ao array mcpServers:

{
  "mcpServers": [
    {
      "name": "gitscrum",
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  ]
}

Se você já tem outros servidores MCP no array, adicione a entrada GitScrum:

{
  "mcpServers": [
    {
      "name": "other-server",
      "command": "other-command",
      "args": ["other-args"]
    },
    {
      "name": "gitscrum",
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  ]
}

Variáveis de Ambiente

O GitScrum MCP Server reconhece as seguintes variáveis de ambiente:

Definindo variáveis de ambiente

Na configuração do cliente (recomendado para configurações por servidor):

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"],
      "env": {
        "GITSCRUM_TOKEN": "seu-token-aqui"
      }
    }
  }
}

No nível do shell (aplica a todos os processos):

# macOS/Linux
export GITSCRUM_TOKEN=seu-token-aqui

# Windows PowerShell
$env:GITSCRUM_TOKEN = "seu-token-aqui"

# Windows CMD
set GITSCRUM_TOKEN=seu-token-aqui

Importante: GITSCRUM_TOKEN contorna o fluxo seguro OAuth. Use apenas em pipelines CI/CD ou ambientes automatizados onde a autenticação via navegador não é prática. Para uso interativo, sempre use o fluxo OAuth Device Grant.

Usando com Docker

Se você executa ambientes de desenvolvimento em containers Docker, pode incluir o servidor MCP na sua configuração Docker.

Dockerfile

FROM node:18-alpine

RUN npm install -g @gitscrum-studio/mcp-server

ENTRYPOINT ["gitscrum-mcp-server"]

Docker Compose com montagem de volume

Para persistir autenticação entre reinicializações do container, monte o diretório de tokens:

services:
  mcp:
    image: node:18-alpine
    command: npx -y @gitscrum-studio/mcp-server
    volumes:
      - ~/.gitscrum:/root/.gitscrum

Docker com variável de ambiente

Para ambientes containerizados, passe o token diretamente:

services:
  mcp:
    image: node:18-alpine
    command: npx -y @gitscrum-studio/mcp-server
    environment:
      - GITSCRUM_TOKEN=${GITSCRUM_TOKEN}

Nota: Ao executar no Docker, o fluxo OAuth Device Grant pode não funcionar como esperado, pois o servidor MCP roda dentro do container mas o navegador está no host. Use GITSCRUM_TOKEN para ambientes Docker.

Argumentos Personalizados do Servidor

O servidor MCP aceita os seguintes argumentos de linha de comando:

Verificando a versão instalada

npx -y @gitscrum-studio/mcp-server --version

Verificando a Conexão

Após configurar seu cliente, verifique se o servidor MCP está funcionando corretamente.

Etapa 1: Verificar se o servidor inicia

Pergunte ao seu assistente de IA:

Verificar status de autenticação do GitScrum

Se o servidor estiver rodando, você receberá uma resposta sobre seu estado de autenticação (seja "autenticado" ou "não autenticado").

Etapa 2: Autenticar

Se não estiver autenticado, faça login:

Fazer login no GitScrum

Complete o fluxo OAuth no navegador conforme descrito em Autenticação.

Etapa 3: Testar uma operação de leitura

Após autenticar, teste com uma leitura simples:

Listar meus workspaces do GitScrum

Você deve ver os nomes dos seus workspaces. Isso confirma:

• O servidor MCP está rodando
• A autenticação está funcionando
• A conexão com a API é válida
• Sua conta tem acesso ao workspace

Etapa 4: Testar uma operação de escrita

Crie uma tarefa de teste para verificar o acesso de escrita:

Criar uma tarefa chamada "Teste do servidor MCP" no [nome do seu projeto]

Se a tarefa for criada com sucesso, seu servidor MCP está totalmente operacional.

Atualizando o Servidor MCP

Com npx (automático)

Se você usa npx -y @gitscrum-studio/mcp-server na sua configuração, as atualizações são automáticas. Cada vez que o servidor MCP inicia, o npx verifica a versão mais recente e a baixa se uma versão mais nova estiver disponível.

Para forçar uma atualização para a versão mais recente:

npx -y @gitscrum-studio/mcp-server@latest --version

Com instalação global

Se você instalou globalmente, atualize manualmente:

npm update -g @gitscrum-studio/mcp-server

Verifique sua versão atual:

npm list -g @gitscrum-studio/mcp-server

Fixação de versão

Para fixar uma versão específica (útil para equipes que precisam de comportamento consistente):

{
  "mcpServers": {
    "gitscrum": {
      "command": "npx",
      "args": ["-y", "@gitscrum-studio/mcp-server@1.2.3"]
    }
  }
}

Substitua 1.2.3 pelo número da versão desejada. Isso previne atualizações automáticas e garante que todos os membros da equipe usem a mesma versão.

Resumo da Configuração

Referência rápida para todos os clientes suportados:

Todos os clientes usam o mesmo comando do servidor MCP:

npx -y @gitscrum-studio/mcp-server

Solução de Problemas de Configuração

Erros de sintaxe JSON

Arquivos de configuração devem conter JSON válido. Erros comuns:

• Vírgulas após a última propriedade em um objeto
• Aspas ausentes ao redor de chaves ou valores string
• Aspas simples em vez de aspas duplas

Use um validador JSON ou o modo de linguagem JSON do seu editor para detectar erros de sintaxe antes de salvar.

Problemas de cache do npx

Se o npx não pegar uma nova versão:

# Limpar o cache do npx
npx clear-npx-cache

# Ou especificar latest explicitamente
npx -y @gitscrum-studio/mcp-server@latest

Erros de permissão no arquivo de token

Se o servidor MCP não consegue ler ou escrever ~/.gitscrum/auth.json:

# macOS/Linux: Corrigir permissões
mkdir -p ~/.gitscrum
chmod 700 ~/.gitscrum
chmod 600 ~/.gitscrum/auth.json

# Windows PowerShell: Verificar se você é o proprietário do arquivo
Get-Acl "$env:USERPROFILE\.gitscrum\auth.json" | Format-List

Node.js não encontrado

Se o cliente reportar que npx ou node não foi encontrado, certifique-se de que o Node.js está no PATH do seu sistema. Alguns clientes (especialmente aplicações desktop) podem não herdar o PATH do seu shell. Você pode fornecer o caminho completo para o npx:

{
  "mcpServers": {
    "gitscrum": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

No Windows, use o caminho completo:

{
  "mcpServers": {
    "gitscrum": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@gitscrum-studio/mcp-server"]
    }
  }
}

Usando MCP Inspector para depuração

A ferramenta MCP Inspector permite interagir com o servidor MCP diretamente, contornando o cliente de IA:

npx @modelcontextprotocol/inspector node dist/index.js

Isso abre um inspector no navegador onde você pode chamar ferramentas individuais e ver respostas brutas. Útil para verificar se o servidor funciona independentemente da configuração do seu cliente de IA.

Próximos Passos

• Início Rápido: Instalação acelerada e primeiros comandos.
• Autenticação: Aprofundamento no fluxo OAuth 2.0 Device Grant.
• Segurança: Modelo de segurança enterprise e boas práticas.
• Visão Geral do MCP: Referência completa de ferramentas com todas as 29 ferramentas e mais de 160 operações.