Jira MCP Server

Servidor MCP para integração com Jira (instância privada – Server/Data Center). Oferece pesquisa por JQL, detalhes de issues e extração de worklogs (horas), com autenticação Basic (usuário e senha).

Requisitos

• Node.js 18+
• Acesso a uma instância Jira (ex.: https://jira.senior.com.br) com usuário e senha

Uso sem baixar os fontes (npx)

Depois que o pacote estiver publicado no npm (público ou registry privado), qualquer pessoa pode usar o MCP sem clonar o repositório. Basta configurar o Cursor com npx:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.senior.com.br",
        "JIRA_USERNAME": "seu_usuario",
        "JIRA_PASSWORD": "sua_senha"
      }
    }
  }
}

• -y evita que o npx pergunte se pode instalar o pacote.
• Na primeira vez o npx baixa o pacote; depois usa o cache.
• Não é necessário ter Node/npm no PATH de forma global em alguns clientes; o Cursor costuma fornecer o ambiente.

Se o pacote estiver em um registry privado (ex.: npm da empresa), use o nome scoped no args, por exemplo: ["-y", "@sua-empresa/jira-mcp-server"].

Configuração (desenvolvimento local)

1. Copie o arquivo de exemplo e preencha com suas credenciais:

   cp .env.example .env

   Edite .env e defina:

   • JIRA_BASE_URL – URL base do Jira (sem barra no final), ex.: https://jira.senior.com.br
   • JIRA_USERNAME – seu usuário do Jira
   • JIRA_PASSWORD – sua senha

2. Instale as dependências e compile:

   npm install
   npm run build

Execução

• Modo stdio (padrão): o Cursor inicia o processo e comunica via stdin/stdout.

  npm start

• Modo HTTP (servidor na rede): o MCP sobe um servidor HTTP e o Cursor conecta por URL. Defina a porta (e opcionalmente o host):

  set JIRA_MCP_HTTP_PORT=8080
  set JIRA_MCP_HTTP_HOST=0.0.0.0
  npm start

  • Sem JIRA_MCP_HTTP_HOST o servidor escuta só em 127.0.0.1 (localhost).
  • Com JIRA_MCP_HTTP_HOST=0.0.0.0 o servidor aceita conexões de qualquer interface (rede local). Em outros PCs use http://<IP-desta-máquina>:8080/mcp no Cursor.
  • No mesmo PC: http://localhost:8080/mcp.
  • Documentação: com o servidor HTTP rodando, acesse http://localhost:8080/mcp/doc para a página de documentação (funcionalidades, configuração e exemplos).

• Modo desenvolvimento (com tsx):

  npm run dev

Logs

Os logs são escritos em stderr (para não interferir no protocolo MCP em stdout). Cada linha é um JSON com ts, level, msg e dados opcionais.

• Nível: definido por JIRA_MCP_LOG_LEVEL: debug | info | warn | error (padrão: info).
• Eventos: início do servidor (baseUrl, user), cada chamada de tool (nome + argumentos), conclusão ou falha da tool, requisições à API Jira (em debug), erros e retentativas.

Para ver mais detalhes (incluindo cada request à API), use JIRA_MCP_LOG_LEVEL=debug no ambiente antes de npm start ou no env do MCP no Cursor.

Configuração no Cursor

1. Abra as configurações do Cursor (MCP / Custom Instructions ou arquivo de configuração de MCPs, ex.: mcp.json).

2. Adicione o servidor de uma das formas abaixo.

   Opção recomendada (sem baixar fontes) – use após publicar no npm:

   • Comando: npx
   • Args: ["-y", "jira-mcp-server"]
   • Env: JIRA_BASE_URL, JIRA_USERNAME, JIRA_PASSWORD

   Opção com fontes locais (desenvolvimento):

   • Comando: node
   • Args: caminho absoluto para jira-mcp-server/dist/index.js
   • Env: as mesmas variáveis acima

   Opção modo HTTP (servidor em localhost): use quando o MCP estiver rodando com JIRA_MCP_HTTP_PORT=8080 (ou outra porta). No Cursor, para servidor remoto/HTTP usa-se url no nível do servidor (não dentro de transport):

   {
     "mcpServers": {
       "jira": {
         "url": "http://localhost:8080/mcp"
       }
     }
   }

   Opcionalmente pode incluir "headers": { ... } se o servidor exigir autenticação por cabeçalho.

   As credenciais do Jira ficam no servidor (variáveis de ambiente onde o npm start foi executado), não no Cursor.

   Não commite o arquivo com senha; use variáveis de ambiente ou secretos quando possível.

Tools disponíveis

| Tool | Descrição | |------|-----------| | jira_check_connection | Valida URL e credenciais; retorna dados do usuário atual ou erro. | | jira_list_projects | Lista projetos acessíveis (key, id, name). | | jira_search_issues | Busca issues por JQL (jql, startAt, maxResults, fields). | | jira_get_issue | Detalhes completos de um issue pelo key. | | jira_get_worklogs | Lista worklogs (horas) de um issue. | | jira_get_issue_or_epic_hours | Total de horas da demanda. Se for Epic, soma as horas das issues vinculadas (onde as horas são lançadas). | | jira_get_issue_estimates | Horas estimadas (Estimated), restantes (Remaining) e gastas (Time spent). Para Epic, soma das issues vinculadas quando a API retorna null no Epic. |

Publicar no npm (para uso via npx)

Para que outros usem o MCP sem clonar o repositório:

1. Registry público: crie conta em npmjs.com, faça npm login e publique:

   npm run build
   npm publish

   O script prepublishOnly roda o build antes de publicar. O campo files faz com que só a pasta dist (e arquivos padrão como package.json) entrem no pacote.

2. Registry privado (ex.: npm da empresa): configure o registry e o nome do pacote (ex.: @sua-empresa/jira-mcp-server no package.json). Depois:

   npm publish --access restricted

   Os usuários precisam estar logados no registry privado para npx @sua-empresa/jira-mcp-server funcionar.

3. Testar localmente antes de publicar: npm pack gera um .tgz; em outro diretório: npm install /caminho/para/jira-mcp-server-1.0.0.tgz e use npx jira-mcp-server de dentro desse projeto para validar.

Instruções customizáveis

No repositório do projeto existe a pasta mcps/user-mcp-jira/ com:

• INSTRUCTIONS.md – Instruções principais de uso do MCP (quando usar cada tool, JQL, fluxos). Edite conforme sua necessidade.
• instructions/ – Arquivos por tema (pesquisas, demandas, horas, custom) para referência ou cópia para o INSTRUCTIONS.md.

Editar esses arquivos permite adaptar o comportamento do assistente ao usar o Jira.

Segurança

• Não commite o arquivo .env nem credenciais em repositórios.
• Use variáveis de ambiente ou secretos do Cursor para JIRA_PASSWORD.
• O cliente não loga credenciais; em caso de erro 401, a mensagem orienta a verificar usuário e senha.