jira-mcp

MCP server para integração com Jira via API Key, empacotado em Docker.

Pré-requisitos

• Docker + Docker Compose
• Node.js 20+ (apenas para dev local)
• API Key do Jira: https://id.atlassian.com/manage-profile/security/api-tokens

---

Setup

1. Crie o arquivo .env

cp .env.example .env
# edite .env com suas credenciais

2. Build da imagem

docker compose build

3. Teste rápido (opcional)

docker run --rm --env-file .env jira-mcp:latest
# deve imprimir: [jira-mcp] Server running — connected to ...

---

Configuração no Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/caminho/absoluto/para/.env",
        "jira-mcp:latest"
      ]
    }
  }
}

Importante: use o caminho absoluto para o .env. O -i mantém o stdin aberto, necessário para o transporte stdio do MCP.

---

Ferramentas disponíveis

Ferramenta	Descrição
jira_get_issue	Detalhes de uma issue pelo key (ex: PROJ-123)
jira_search_issues	Busca com JQL
jira_create_issue	Cria nova issue
jira_update_issue	Atualiza campos de uma issue
jira_add_comment	Adiciona comentário
jira_get_transitions	Lista transições disponíveis
jira_transition_issue	Move issue para novo status
jira_get_projects	Lista todos os projetos
jira_whoami	Retorna info do usuário autenticado

---

Exemplos de JQL

# Issues abertas no projeto PROJ
project = PROJ AND status != Done ORDER BY updated DESC

# Minhas issues em andamento
assignee = currentUser() AND status = "In Progress"

# Bugs de alta prioridade criados essa semana
issuetype = Bug AND priority in (High, Highest) AND created >= startOfWeek()

# Issues sem responsável num projeto
project = PROJ AND assignee is EMPTY

---

Dev local (sem Docker)

npm install
cp .env.example .env   # preencha as variáveis
npx ts-node src/index.ts

---

Segurança

• Credenciais carregadas via variáveis de ambiente, nunca no código
• Container roda como usuário não-root (mcp)
• read_only: true e cap_drop: ALL no compose
• API Key nunca é logada (redactada em mensagens de erro)