jira-easy-mcp

Jira Server/Data Center 7-10 auto-hospedado para agentes de IA com nome de usuário e senha. 42 ferramentas.

Documentação

jira-easy-mcp

Outro servidor Model Context Protocol (MCP) para Jira, sem token de autenticação. Fornece ferramentas para automação completa do Jira, incluindo issues, projetos, quadros, sprints, comentários, apontamentos de horas e muito mais.

Testado em: Jira Server / Data Center 7.13, 8.20, 9.12 e 10.3 (todas as ferramentas, automatizado, veja Desenvolvimento e Testes)

🔑 Por que este MCP?

Funciona com Autenticação Básica (usuário + senha) — sem necessidade de tokens de API!

A maioria dos servidores MCP para Jira exige OAuth ou tokens de API, que muitas organizações restringem ou não permitem. Este MCP usa Autenticação Básica HTTP, então você pode se conectar usando apenas seu usuário e senha do Jira. Perfeito para:

🏢 Ambientes corporativos onde administradores não permitem a criação de tokens de API
🔒 Instâncias Jira Server auto-hospedadas sem OAuth configurado
⚡ Configuração rápida sem passar por processos de aprovação de TI

Início Rápido

VS Code (Configuração do Workspace)

Crie .vscode/mcp.json na raiz do seu workspace:

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jira-easy-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_PASSWORD": "your-password",
        "JIRA_PROJECTS_FILTER": "ABC,DEF,XYZ",
        "JIRA_RESPONSE_FORMAT": "JSON"
      }
    }
  }
}

Adicione às configurações do VS Code para acessar em todos os workspaces.

Nota: JIRA_PROJECTS_FILTER e JIRA_RESPONSE_FORMAT são opcionais. O filtro de projetos limita o acesso aos projetos especificados. O formato de resposta pode ser JSON (padrão) ou TOON (notação orientada a texto).

Claude Code

claude mcp add jira \
  -e JIRA_BASE_URL=https://your-jira-instance.com \
  -e JIRA_USERNAME=your-username \
  -e JIRA_PASSWORD=your-password \
  -- npx -y jira-easy-mcp

Codex CLI

Adicione ao ~/.codex/config.toml:

[mcp_servers.jira]
command = "npx"
args = ["-y", "jira-easy-mcp"]
env = { JIRA_BASE_URL = "https://your-jira-instance.com", JIRA_USERNAME = "your-username", JIRA_PASSWORD = "your-password" }

Outros clientes

Cursor: ~/.cursor/mcp.json ou .cursor/mcp.json (use o wrapper "mcpServers": { ... })
Windsurf: Adicione às configurações MCP do Windsurf (use o wrapper "mcpServers": { ... })
Claude Desktop: Edite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\; use o wrapper "mcpServers": { ... })
Gemini CLI: ~/.gemini/settings.json (use o wrapper "mcpServers": { ... })

Todos usam a mesma configuração de command, args e env do VS Code acima.

Windows: se o cliente não conseguir iniciar npx, use "command": "cmd" com "args": ["/c", "npx", "-y", "jira-easy-mcp"].

Limites de ferramentas: alguns clientes (notadamente o Cursor) limitam quantas ferramentas enviam ao modelo, historicamente em torno de 40 em todos os servidores. Este servidor tem 41; desative as que não precisar nas configurações MCP do cliente.

Credenciais do chaveiro do sistema operacional (opcional)

Para manter sua senha fora dos arquivos de configuração, omita JIRA_USERNAME/JIRA_PASSWORD e armazene uma credencial sob o nome de serviço JiraMCP:

macOS: security add-generic-password -s JiraMCP -a your-username -w (solicita a senha; no primeiro início, o macOS pede permissão para node lê-la)
Windows: cmdkey /generic:JiraMCP /user:your-username /pass (use /generic, não /add)

Se várias contas estiverem armazenadas, defina JIRA_USERNAME para escolher uma. Quando JIRA_USERNAME e JIRA_PASSWORD estiverem definidos, eles serão usados e o chaveiro não será lido. O suporte a chaveiro usa o pacote opcional keytar; se não puder ser instalado na sua máquina, use as variáveis de ambiente.

Casos de Uso Comuns

Tarefa	Ferramenta	Exemplo de Prompt
Pesquisar issues	`jira_search`	"Pesquise todos os bugs abertos atribuídos a mim no projeto ABC"
Obter detalhes da issue	`jira_get_issue`	"Mostre-me os detalhes da issue ABC-123"
Ver imagens da issue	`jira_get_issue_images`	"Mostre-me as capturas de tela anexadas a ABC-123"
Enviar anexo	`jira_upload_attachment`	"Anexe /Users/me/Desktop/error.png a ABC-123"
Criar issue	`jira_create_issue`	"Crie um novo bug no projeto ABC com o título 'Botão de login não funciona'"
Atualizar issue	`jira_update_issue`	"Altere a prioridade de ABC-123 para Alta e atribua a john.doe"
Editar campos personalizados	`jira_update_issue` + `jira_get_edit_meta`	"Defina Severidade como Crítica em ABC-123" (nome único ou id `customfield_`)
Adicionar comentário	`jira_add_comment`	"Adicione um comentário a ABC-123 dizendo 'Correção implantada no staging'"
Alterar status	`jira_transition_issue`	"Mova ABC-123 para Concluído"
Registrar horas	`jira_add_worklog`	"Registre 2 horas de trabalho em ABC-123 para ontem"
Listar projetos	`jira_get_projects`	"Mostre-me todos os projetos aos quais tenho acesso"
Ver sprints	`jira_get_sprints`	"O que está no sprint atual do projeto ABC?"
Vincular issues	`jira_create_link`	"Vincule ABC-123 como bloqueando ABC-124"
Gerar URL de filtro	`jira_generate_filter_url`	"Crie um link compartilhável para todos os bugs abertos atualizados nos últimos 7 dias"

Testando com o MCP Inspector

O MCP Inspector fornece uma interface web para testar todas as ferramentas interativamente:

npx @modelcontextprotocol/inspector npx jira-easy-mcp

Isso abre um navegador em http://localhost:6274 onde você pode:

Ver todas as ferramentas disponíveis
Testar cada ferramenta com parâmetros personalizados
Ver as respostas JSON brutas

Nota: Coloque esses valores na interface do inspector antes de conectar: JIRA_BASE_URL, JIRA_USERNAME, JIRA_PASSWORD.

Campos personalizados

A API REST v2 do Jira identifica campos personalizados por id (customfield_10006). Os valores são o payload REST bruto para aquele tipo de campo. Nomes de exibição funcionam apenas quando são únicos (exatos, sensíveis a maiúsculas/minúsculas) na tela relevante.

Leitura (`jira_get_issue`)

Resposta padrão: campos do sistema mais campos personalizados que atualmente têm valor, cada um como { "id", "name", "value" }. Comentários, apontamentos de horas e anexos são omitidos a menos que você passe include: ["comments"] (e/ou worklogs, attachments). Campos personalizados nulos são omitidos a menos que customFields: "all" ou você passe fields.

fields restringe o GET de campos personalizados (ids como customfield_11205, ou nomes únicos de tela de edição como Severity). Os campos solicitados são retornados mesmo quando nulos. Os nomes vêm do expand=names desta issue, não do GET /field.

{
  "key": "ABC-123",
  "customFields": [
    { "id": "customfield_10006", "name": "Story Points", "value": 5 },
    { "id": "customfield_10107", "name": "Flagged", "value": { "value": "Yes" } }
  ]
}

Escrita (`jira_update_issue` / `jira_create_issue`)

Passe customFields chaveado por id (customfield_10006) ou por um nome único de jira_get_edit_meta / jira_get_create_meta. Ids não precisam de GET extra. Nomes são resolvidos contra o meta daquele tipo de issue; nomes duplicados falham de forma segura (use o id). Não chame jira_get_fields antes de cada escrita.

Schema `type`	Valor REST
string / número / data	`"text"`, `5`, `"2011-10-03"`
opção (select)	`{ "value": "Yes" }` ou `{ "id": "10100" }`
usuário (Server)	`{ "name": "username" }` — não Cloud `accountId`
array de opções	`[{ "value": "A" }, { "value": "B" }]` (`itemsType`: `option`)
limpar	`null`

Um campo listado por jira_get_fields mas ausente do meta de edição/criação não está naquela tela e não pode ser atualizado.

Pesquisa (`jira_search`)

A pesquisa padrão retorna apenas campos do sistema (sem campos personalizados, sem despejos de comentário/apontamento de horas/anexo). fields é extras aditivos: chaves do sistema e ids customfield_ passam; nomes de exibição são resolvidos com um GET /field ao vivo sem cache. Prefira ids. Nomes ambíguos falham de forma segura.

Catálogo (`jira_get_fields`)

Use isso para nomes de cláusulas JQL, não como um pré-passo para cada criação/atualização. Para campos em um tipo de issue, use jira_get_edit_meta ou jira_get_create_meta.

Variáveis de Ambiente Opcionais

Variável	Padrão	Descrição
`JIRA_PROJECTS_FILTER`	(nenhum)	Chaves de projeto separadas por vírgula. As ferramentas rejeitam chaves de issue/projeto fora da lista (ids de issue devem ser fornecidos como chaves) e o JQL é limitado a esses projetos. Ids de quadro, sprint e link não são verificados
`JIRA_RESPONSE_FORMAT`	`JSON`	Formato de resposta: `JSON` ou `TOON`
`JIRA_LOG_LEVEL`	`INFO`	Verbosidade do log: `DEBUG`, `INFO`, `WARN`, `ERROR`
`JIRA_TIMEOUT`	`30000`	Tempo limite de solicitação em milissegundos
`JIRA_RETRY_COUNT`	`3`	Tentativas para timeouts, 429 e 502-504. Solicitações de escrita (POST) são repetidas apenas em 429, então um Jira lento nunca gera issues, comentários ou links duplicados
`JIRA_RETRY_DELAY`	`1000`	Atraso base entre tentativas (ms)
`JIRA_SSL_VERIFY`	`true`	Defina como `false` para pular a verificação SSL. Para uma CA corporativa, prefira `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`
`JIRA_CACHE_TTL`	`300`	TTL de cache em segundos para dados estáticos

jira_get_issue_images baixa imagens através das URLs de anexo autenticadas do Jira (/secure/attachment/..., Jira Server/Data Center). Retorna até cinco imagens por padrão (máximo de dez), com limite de 10 MiB por imagem e 20 MiB por resposta. jira_upload_attachment lê um arquivo local por caminho absoluto na máquina que executa o servidor.

Solução de Problemas

Erro	Correção
`Authentication failed ... restart the MCP server`	Credenciais incorretas. Após a primeira falha, o servidor para de tentar login, então tentativas repetidas do agente não podem acionar o bloqueio CAPTCHA do Jira. Corrija as credenciais e reinicie o servidor (ou recarregue os servidores MCP no seu cliente).
`Login blocked by CAPTCHA`	Muitos logins com falha. Faça login no Jira uma vez no navegador e tente novamente.
`Jira redirected to ...`	`JIRA_BASE_URL` está desativado: use `https://` se o Jira redirecionar para lá, ou adicione o caminho de contexto. Um redirecionamento para uma página de login significa que um proxy SSO está na frente do Jira.
`No Jira REST API at ...`	Geralmente um caminho de contexto ausente, ex.: `https://host/jira` em vez de `https://host`.
`fetch failed` / erros de certificado	CA corporativa: inicie o servidor com `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`. Último recurso: `JIRA_SSL_VERIFY=false`.
`... outside the allowed projects`	A chave não está em `JIRA_PROJECTS_FILTER`.

Desenvolvimento e Testes

pnpm install
pnpm test              # unit tests + build (any OS, Node 18+)
node scripts/smoke.mjs # MCP handshake check (needs JIRA_BASE_URL set to anything)

Contra um Jira real (Docker, Node 20.10+): o helper inicia um Jira descartável, conclui a configuração com a licença pública de 3 horas do Atlassian, e cria um admin (admin / Jira-IT-admin-1), um segundo usuário e dois projetos Scrum (IT, OT).

pnpm jira:up 9.12 8080            # or 7.13, 8.20, 10.3 (Jira 10 also starts PostgreSQL)
JIRA_IT_BASE_URL=http://localhost:8080 pnpm test:integration
pnpm jira:down 9.12

pnpm jira:up 9.12 8080 /jira serve o Jira sob um caminho de contexto. Cada instância precisa de cerca de 3 GB de memória Docker; execute uma por vez em máquinas pequenas. Os testes de chaveiro só rodam onde keytar funciona e nenhuma credencial real de JiraMCP existe, e eles removem o que criam. O CI executa os testes unitários no Linux, macOS e Windows (Node 18-24) e a suíte de integração contra cada versão acima.

Compatibilidade

Versão do Jira	Status
Jira Server 7.12.1 / 7.12.3	✅ Testado manualmente
Jira Server 7.13	✅ Automatizado (todas as ferramentas)
Jira Server / DC 8.20	✅ Automatizado (todas as ferramentas)
Jira DC 9.12 (também sob caminho de contexto `/jira`)	✅ Automatizado (todas as ferramentas)
Jira DC 10.3	✅ Automatizado (todas as ferramentas)
Jira Cloud	︖ Não testado (use o MCP oficial)

Requer Node.js 18+. O CI executa os testes unitários e de fumaça MCP no macOS, Linux e Windows (Node.js 18–24).

Você pode melhorar isso relatando problemas

jira-easy-mcp

Documentação

jira-easy-mcp

🔑 Por que este MCP?

Início Rápido

VS Code (Configuração do Workspace)

Claude Code

Codex CLI

Outros clientes

Credenciais do chaveiro do sistema operacional (opcional)

Casos de Uso Comuns

Testando com o MCP Inspector

Campos personalizados

Leitura (jira_get_issue)

Escrita (jira_update_issue / jira_create_issue)

Pesquisa (jira_search)

Catálogo (jira_get_fields)

Variáveis de Ambiente Opcionais

Solução de Problemas

Desenvolvimento e Testes

Compatibilidade

Leitura (`jira_get_issue`)

Escrita (`jira_update_issue` / `jira_create_issue`)

Pesquisa (`jira_search`)

Catálogo (`jira_get_fields`)