🚀 Jira MCP Server - Claro Digital

Model Context Protocol (MCP) server for Jira integration - permite gerenciar suas tarefas Jira diretamente através do Claude de forma conversacional.

🎯 O que é isso?

Este é um MCP Server que conecta o Claude ao Jira da Claro Digital, permitindo:

• 📋 Consultar suas tarefas e subtarefas

• ⏱️ Registrar tempo trabalhado (worklogs)

• 💬 Adicionar comentários para rastreabilidade

• 🔍 Executar queries JQL personalizadas

Tudo através de conversação natural com assistentes de IA!

Related MCP server: JIRA MCP Server

🌐 Compatibilidade Multi-Editor

Este MCP server funciona em qualquer editor que suporte o Model Context Protocol:

• ✅ Claude Code - Suporte nativo

• ✅ Cursor - Configuração por projeto (.cursor/mcp.json)

• ✅ VS Code + GitHub Copilot - GA desde v1.102

• 🟡 JetBrains IDEs - Preview via AI Assistant

• 🟡 Visual Studio - Preview

• 🟡 Eclipse - Preview

MCP é um protocolo aberto (não exclusivo do Claude!) - funciona com qualquer cliente compatível!

✨ Funcionalidades

10 Tools Disponíveis:

Queries (6 tools):

• list_my_tasks - Lista todas suas tarefas

• list_subtasks - Lista subtarefas (com filtros)

• list_sprint_active - Tarefas da sprint ativa

• list_in_development - Tarefas em desenvolvimento

• list_projects - Lista projetos disponíveis

• custom_query - Execute JQL customizado

Worklogs (2 tools):

• add_worklog - Registrar tempo em uma issue

• list_worklogs - Ver registros de tempo

Comments (2 tools):

• add_comment - Adicionar comentário

• list_comments - Ver comentários

🏗️ Arquitetura

jira-mcp-server/
├── src/
│   ├── index.ts           # MCP Server principal
│   ├── jira-client.ts     # Client da API Jira
│   ├── tools/
│   │   ├── queries.ts     # Tools de queries
│   │   ├── worklog.ts     # Tools de worklog
│   │   └── comments.ts    # Tools de comments
│   └── types/
│       └── jira.ts        # TypeScript types
├── dist/                  # Código compilado
├── package.json
├── tsconfig.json
├── .env                   # Suas credenciais (não commitar!)
└── .env.example           # Template

🚀 Quick Start

1. Instalar Dependências

cd jira-mcp-server
npm install

2. Configurar Credenciais

Copie .env.example para .env e preencha:

cp .env.example .env

Edite .env:

JIRA_URL=https://clarodigital.atlassian.net
JIRA_EMAIL=seu-email@claro.com.br
JIRA_API_TOKEN=seu-token-aqui

Gerar API Token: https://id.atlassian.com/manage/api-tokens

3. Compilar TypeScript

npm run build

4. Configurar no Claude Code

Edite ~/.config/claude/claude_desktop_config.json (ou ~/Library/Application Support/Claude/claude_desktop_config.json no Mac):

{
  "mcpServers": {
    "jira-claro": {
      "command": "node",
      "args": ["/caminho/absoluto/para/jira-mcp-server/dist/index.js"],
      "env": {
        "JIRA_URL": "https://clarodigital.atlassian.net",
        "JIRA_EMAIL": "seu-email@claro.com.br",
        "JIRA_API_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Importante: Use o caminho absoluto para o arquivo dist/index.js!

5. Reiniciar Claude Code

Feche e abra o Claude Code novamente para carregar o MCP server.

💬 Exemplos de Uso

Após configurar, você pode conversar com o Claude assim:

Você: "Mostre minhas subtarefas da sprint atual"

Claude: [usa list_subtasks]
📋 Found 6 subtasks:

**CCOE-82835**: Implementar políticas de branch protection
Status: To Development | Priority: Medium | Assignee: pedro.hedro...
Updated: 2025-10-06

**CCOE-82834**: Configurar templates de PR
Status: To Development | Priority: Medium | Assignee: pedro.hedro...
Updated: 2025-10-06
...

Você: "Adicione 2 horas de worklog em CCOE-82835 com comentário 'Desenvolvimento da feature'"

Claude: [usa add_worklog]
✅ Worklog added successfully to **CCOE-82835**
⏱️  Time logged: 2h (2h 0m)
💬 Comment: Desenvolvimento da feature

Você: "Adicione comentário em CCOE-82835: 'Iniciando desenvolvimento'"

Claude: [usa add_comment]
✅ Comment added successfully to **CCOE-82835**
👤 Author: pedro.hedro@globalhitss.com.br
📅 Created: 2025-10-06
💬 Comment: Iniciando desenvolvimento

📚 Documentação Detalhada

Setup por Editor

• SETUP.md - Guia completo para Claude Code

• CURSOR_SETUP.md - Guia completo para Cursor

• VSCODE_COPILOT_SETUP.md - Guia completo para VS Code + GitHub Copilot

Referências

• TOOLS.md - Documentação de cada tool disponível (todos os editores)

• SHARING.md - Como compartilhar com sua equipe

🤝 Compartilhamento com Colegas

Opção 1: Local Install (Mais Simples)

1. Compartilhe o repositório:

zip -r jira-mcp-server.zip jira-mcp-server/
# Enviar arquivo para colegas

2. Colegas descompactam e seguem Quick Start

Opção 2: Git Clone

git clone https://github.com/TechTeam-ClaroEmpresas/jira-mcp-server
cd jira-mcp-server
npm install
cp .env.example .env
# Editar .env com credenciais
npm run build
# Configurar no claude_desktop_config.json

Opção 3: NPM (Futuro)

Planejado para publicação no npm interno da Claro

🔒 Segurança

• ✅ Credenciais via .env - Nunca hardcode tokens

• ✅ .gitignore configurado - .env nunca é commitado

• ✅ HTTPS-only - Comunicação segura com API Jira

• ✅ Token pessoal - Cada pessoa usa seu próprio token

🛠️ Desenvolvimento

Scripts Disponíveis

npm run build       # Compilar TypeScript
npm run watch       # Compilar em modo watch
npm run dev         # Rodar em modo desenvolvimento

Estrutura de Tools

Cada tool segue o padrão:

{
  description: string,
  inputSchema: z.object({...}),  // Validação com Zod
  handler: async (args) => {
    // Lógica do tool
    return {
      content: [{ type: 'text', text: '...' }]
    };
  }
}

🐛 Troubleshooting

MCP Server não aparece no Claude

1. Verifique o caminho em claude_desktop_config.json

2. Use caminho absoluto (não relativo)

3. Reinicie o Claude Code completamente

4. Verifique logs em ~/Library/Logs/Claude/mcp*.log (Mac)

Erro de Autenticação

1. Verifique se o .env está preenchido corretamente

2. Gere um novo API token: https://id.atlassian.com/manage/api-tokens

3. Certifique-se que o email está correto

Tools não funcionam

1. Verifique se você tem permissão na issue

2. Para worklog: use formato correto ("2h 30m", "1d", etc)

3. Veja logs para mensagens de erro detalhadas

📊 Tecnologias Usadas

• TypeScript - Type safety

• @modelcontextprotocol/sdk - SDK oficial MCP

• axios - HTTP client

• zod - Schema validation

• dotenv - Environment variables

🔄 Changelog

v1.0.1 (2025-10-07)

• ✅ API Migration: Atualizado para usar a nova API do Jira /rest/api/3/search/jql (POST)

• A API antiga /rest/api/3/search (GET) foi descontinuada pela Atlassian

• Referência: CHANGE-2046

🎓 Learn More

• Model Context Protocol

• Jira REST API Documentation

• Claude Code Documentation

👥 Autores

• Pedro Hedro - Initial work - pedro.hedro@globalhitss.com.br

• Claro Digital Team - CCoE

📝 License

MIT

Made with ❤️ by Claro Digital Team