Servidor MCP Jira | Awesome MCP Servers

Servidor MCP Jira para Jira Auto-hospedado

Um servidor Model Context Protocol (MCP) para interagir com instâncias Jira auto-hospedadas usando autenticação por Personal Access Token (PAT).

Recursos

✅ Autenticação por Personal Access Token para Jira auto-hospedado
✅ Criar, ler, atualizar e excluir issues do Jira
✅ Pesquisar issues usando JQL (Jira Query Language)
✅ Adicionar e visualizar comentários
✅ Gerenciar atribuições de issues
✅ Listar projetos e tipos de issue
✅ Transicionar issues entre status
✅ Obter informações do usuário atual

Pré-requisitos

Node.js 18 ou superior
Uma instância Jira auto-hospedada (ex.: https://jira.domain.com)
Um Personal Access Token do Jira

Como Criar um Personal Access Token no Jira Auto-hospedado

Faça login na sua instância Jira (ex.: https://jira.domain.com)
Clique no ícone do seu perfil no canto superior direito
Selecione "Profile" ou "Account Settings"
Navegue até "Personal Access Tokens" ou "Security"
Clique em "Create token"
Dê um nome ao seu token (ex.: "MCP Server")
Defina uma data de expiração (opcional, mas recomendado)
Clique em "Create"
Copie o token imediatamente - você não poderá vê-lo novamente!

Instalação

Opção 1: Usando npm (Recomendado)

Uso direto com npx:

npx mcp-jira-server

Ou instale globalmente:

npm install -g mcp-jira-server

Opção 2: A partir do código-fonte

Clone o repositório:

git clone https://github.com/edrich13/mcp-jira-server.git
cd mcp-jira-server

Instale as dependências:

npm install

Compile o servidor:

npm run build

Configuração

Para o Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Opção 1: Usando npx (Recomendado)

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Opção 2: Usando build do código-fonte

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/edrich.rocha/.nvm/versions/node/v22.6.0/bin/mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Para VS Code com MCP

Crie ou atualize .vscode/mcp.json no seu workspace:

Opção 1: Usando npx (Recomendado)

{
  "servers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Opção 2: Usando build do código-fonte

{
  "servers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/build/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.domain.com",
        "JIRA_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Variáveis de Ambiente

JIRA_BASE_URL: A URL base da sua instância Jira auto-hospedada (ex.: https://jira.domain.com)
JIRA_PAT: Seu Personal Access Token
JIRA_USER_AGENT (opcional): Cabeçalho User-Agent personalizado para instâncias Jira atrás de proxies reversos (oauth2-proxy, nginx, etc.) que filtram requisições por User-Agent. Se suas requisições de API forem redirecionadas para login SSO apesar de um PAT válido, seu proxy reverso pode exigir um User-Agent específico para ignorar a autenticação para clientes de API.

Ferramentas Disponíveis

1. `jira_get_issue`

Obtenha detalhes de uma issue específica do Jira pela sua chave.

Parâmetros:

issueKey (string, obrigatório): A chave da issue do Jira (ex.: "PROJ-123")

Exemplo:

Get details for issue PROJ-123

2. `jira_search_issues`

Pesquise issues do Jira usando JQL (Jira Query Language).

Parâmetros:

jql (string, obrigatório): String de consulta JQL
maxResults (número, opcional): Número máximo de resultados (padrão: 50)

Exemplo:

Search for all open issues in project PROJ assigned to me

Exemplos Comuns de JQL:

project = PROJ AND status = Open
assignee = currentUser() AND status != Done
priority = High AND created >= -7d
reporter = john.doe AND status IN (Open, "In Progress")

3. `jira_create_issue`

Crie uma nova issue no Jira.

Parâmetros:

projectKey (string, obrigatório): Chave do projeto
summary (string, obrigatório): Título/resumo da issue
issueType (string, obrigatório): Tipo da issue (ex.: "Bug", "Task", "Story")
description (string, opcional): Descrição detalhada
priority (string, opcional): Nível de prioridade (ex.: "High", "Medium", "Low")
assignee (string, opcional): Nome de usuário para atribuir
labels (array, opcional): Array de rótulos
components (array, opcional): Array de nomes de componentes
Campos personalizados: Quaisquer parâmetros adicionais prefixados com customfield_ (ex.: customfield_10001)

Exemplo:

Create a new bug in project PROJ with summary "Login page not loading" and high priority

Exemplo de Campos Personalizados:

Create a story in PROJ with custom field customfield_10001 set to "Sprint 1"

4. `jira_update_issue`

Atualize uma issue existente do Jira.

Parâmetros:

issueKey (string, obrigatório): Chave da issue a ser atualizada
summary (string, opcional): Novo resumo
description (string, opcional): Nova descrição
assignee (string, opcional): Novo nome de usuário do responsável
priority (string, opcional): Nova prioridade
labels (array, opcional): Novo array de rótulos
status (string, opcional): Novo status (ex.: "In Progress", "Done")
Campos personalizados: Quaisquer parâmetros adicionais prefixados com customfield_ (ex.: customfield_10002)

Exemplo:

Update issue PROJ-123 to set status to "In Progress" and assign to john.doe

5. `jira_add_comment`

Adicione um comentário a uma issue do Jira.

Parâmetros:

issueKey (string, obrigatório): Chave da issue
comment (string, obrigatório): Texto do comentário

Exemplo:

Add a comment to PROJ-123 saying "Fixed in latest deployment"

6. `jira_get_comments`

Obtenha todos os comentários de uma issue do Jira.

Parâmetros:

issueKey (string, obrigatório): Chave da issue

7. `jira_get_projects`

Liste todos os projetos Jira disponíveis.

Parâmetros: Nenhum

Exemplo:

List all Jira projects

8. `jira_get_project`

Obtenha detalhes de um projeto específico.

Parâmetros:

projectKey (string, obrigatório): Chave do projeto

9. `jira_get_issue_types`

Obtenha os tipos de issue disponíveis para um projeto.

Parâmetros:

projectKey (string, obrigatório): Chave do projeto

10. `jira_assign_issue`

Atribua uma issue do Jira a um usuário.

Parâmetros:

issueKey (string, obrigatório): Chave da issue
assignee (string, obrigatório): Nome de usuário para atribuir

11. `jira_delete_issue`

Exclua uma issue do Jira permanentemente.

Parâmetros:

issueKey (string, obrigatório): Chave da issue a ser excluída

⚠️ Aviso: Esta ação é permanente e não pode ser desfeita.

12. `jira_get_current_user`

Obtenha informações sobre o usuário atualmente autenticado.

Parâmetros: Nenhum

Desenvolvimento

Compilar o servidor

npm run build

Modo de observação para desenvolvimento

npm run watch

Executar em modo de desenvolvimento

npm run dev

Testando o Servidor

Após configurar o servidor, reinicie o Claude Desktop ou o VS Code para carregar o novo servidor MCP.

Comandos Rápidos de Teste

Testar autenticação:
```
Get my current Jira user information
```
Listar projetos:
```
Show me all Jira projects
```

Pesquisar issues:

Search for all issues assigned to me that are not done

Criar uma issue:

Create a new task in project PROJ with summary "Test MCP integration"

Solução de Problemas

Servidor não conectando

Verifique o caminho absoluto na sua configuração
Certifique-se de que o servidor foi compilado (npm run build)
Verifique se as variáveis de ambiente estão definidas corretamente
Reinicie o Claude Desktop ou o VS Code após alterações na configuração

Erros de autenticação

Verifique se o seu Personal Access Token ainda é válido
Verifique se o token não expirou
Certifique-se de que o token tenha as permissões adequadas
Verifique se o JIRA_BASE_URL está correto (sem barra final)

Erros de API

Verifique os logs do servidor Jira para mensagens de erro detalhadas
Verifique se a API do Jira está acessível a partir da sua máquina
Certifique-se de que sua conta de usuário tenha as permissões necessárias
Tente acessar a API REST diretamente: https://jira.domain.com/rest/api/2/myself

Problemas comuns

"Cannot find module": Execute npm install e npm run build
"Connection refused": Verifique se o servidor Jira está acessível e se a URL está correta
"Unauthorized": Verifique o seu Personal Access Token
"Issue type not found": Use jira_get_issue_types para ver os tipos válidos para o projeto
Requisições de API redirecionadas para login SSO: Seu Jira pode estar atrás de um proxy reverso (oauth2-proxy, nginx) que filtra por User-Agent. Defina a variável de ambiente JIRA_USER_AGENT com uma string User-Agent na lista de permissões. Contate seu administrador de sistema para obter o valor de User-Agent permitido.

Boas Práticas de Segurança

Nunca envie seu Personal Access Token para controle de versão
Armazene tokens com segurança em arquivos de configuração com permissões restritas
Use tokens com as permissões mínimas necessárias
Defina datas de expiração para tokens
Rotacione tokens regularmente
Monitore o uso de tokens nos logs de auditoria do Jira

Referência da API

Este servidor MCP usa a Jira REST API v2. Para mais informações sobre a API do Jira:

Documentação da API REST do Jira: https://your-jira-instance/rest/api/2/
Guia de sintaxe JQL: Consulte a documentação da sua instância Jira

Licença

MIT

Suporte

Para problemas relacionados a:

Servidor MCP: Verifique os logs no Claude Desktop ou VS Code
API do Jira: Consulte a documentação do seu Jira auto-hospedado
Autenticação: Contate seu administrador do Jira

Contribuindo

Contribuições são bem-vindas! Por favor, certifique-se de que:

O código segue as boas práticas de TypeScript
Todas as ferramentas estão devidamente documentadas
O tratamento de erros seja abrangente
As boas práticas de segurança sejam seguidas

Jira MCP

Documentação

Servidor MCP Jira para Jira Auto-hospedado

Recursos

Pré-requisitos

Como Criar um Personal Access Token no Jira Auto-hospedado

Instalação

Opção 1: Usando npm (Recomendado)

Opção 2: A partir do código-fonte

Configuração

Para o Claude Desktop

Para VS Code com MCP

Variáveis de Ambiente

Ferramentas Disponíveis

1. jira_get_issue

2. jira_search_issues

3. jira_create_issue

4. jira_update_issue

5. jira_add_comment

6. jira_get_comments

7. jira_get_projects

8. jira_get_project

9. jira_get_issue_types

10. jira_assign_issue

11. jira_delete_issue

12. jira_get_current_user

Desenvolvimento

Compilar o servidor

Modo de observação para desenvolvimento

Executar em modo de desenvolvimento

Testando o Servidor

Comandos Rápidos de Teste

Solução de Problemas

Servidor não conectando

Erros de autenticação

Erros de API

Problemas comuns

Boas Práticas de Segurança

Referência da API

Licença

Suporte

Contribuindo

1. `jira_get_issue`

2. `jira_search_issues`

3. `jira_create_issue`

4. `jira_update_issue`

5. `jira_add_comment`

6. `jira_get_comments`

7. `jira_get_projects`

8. `jira_get_project`

9. `jira_get_issue_types`

10. `jira_assign_issue`

11. `jira_delete_issue`

12. `jira_get_current_user`