Skip to main content
Glama
Jira MCP Server

Jira MCP Server

by pedrohedro

🚀 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

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
  1. 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

đŸ‘„ Autores

📝 License

MIT


Made with ❀ by Claro Digital Team

Available Tools

22 tools
add_attachmentA

Add attachment to a Jira issue (provide file path)

Inputs: filePath (required), issueKey (required).

add_commentB

Add a comment to an issue or subtask for traceability

Inputs: issueKey (required), commentText (required).

add_worklogB

Add time log (worklog) to an issue or subtask

Inputs: issueKey (required), timeSpent (required), comment.

create_confluence_pageB

Create a new Confluence page in a specific space

Inputs: body (required), title (required), spaceKey (required), parentId.

create_issueA

Create a new Jira issue with specified fields. For CCOE project, required fields (3F and Tipo) are auto-filled with defaults if not provided. Use ccoe3F and ccoeType parameters for easy selection, or customFields for full control.

Inputs: project (required), summary (required), ccoe3F, labels, +9 more.

custom_queryC

Execute custom JQL query

Inputs: jql (required), maxResults.

get_confluence_pageB

Get the content of a Confluence page by ID

Inputs: pageId (required).

get_issue_custom_fieldsA

Get custom field values from an existing issue (useful for discovering field IDs)

Inputs: issueKey (required).

get_project_issue_typesA

Get available issue types for a project (useful for finding issue type IDs)

Inputs: project (required).

list_attachmentsA

List all attachments for a Jira issue

Inputs: issueKey (required).

list_commentsA

List all comments for an issue

Inputs: issueKey (required).

list_in_developmentC

List tasks currently in development

Inputs: maxResults.

list_my_board_tasksA

List all tasks assigned to current user in CCOE project board (Atlantis P&D) - Use terminal commands for board-specific searches

Inputs: maxResults.

list_my_tasksA

List all unresolved tasks assigned to current user

Inputs: maxResults.

list_projectsA

List all available Jira projects

Inputs: no named parameters.

list_sprint_activeB

List all tasks in active sprint assigned to current user

Inputs: maxResults.

list_subtasksB

List all subtasks assigned to current user

Inputs: sprint, status.

list_worklogsA

List all worklogs for an issue

Inputs: issueKey (required).

search_confluenceB

Search Confluence pages using CQL (Confluence Query Language)

Inputs: cql (required), limit.

update_confluence_pageB

Update the content of an existing Confluence page

Inputs: body (required), title (required), pageId (required), versionNumber (required).

update_issueB

Update fields of an existing Jira issue

Inputs: issueKey (required), labels, summary, assignee, +3 more.

update_issue_statusA

Update the status of a Jira issue (transition workflow)

Inputs: status (required), issueKey (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog


    TDQS

    B3.1/5.0

    Scored across 22 tools

    Disambiguation2/5

    Several tools overlap in purpose: list_my_tasks, list_subtasks, list_sprint_active, list_in_development, and list_my_board_tasks all list tasks assigned to the current user with only subtle filter differences. custom_query can also replicate these searches, making tool boundaries unclear.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun snake_case pattern (e.g., list_projects, create_issue, add_comment, get_confluence_page). Minor deviations include custom_query (not verb_noun) and update_issue_status (three-part), but the overall style is predictable.

    Tool Count3/5

    With 22 tools, the server is on the heavier side for a Jira+Confluence integration. While not extreme, the count falls in the 16-25 range that feels somewhat bloated but still manageable for the scope.

    Completeness3/5

    Core workflows are covered: issue creation/update/status, comments, worklogs, attachments, JQL queries, and Confluence get/search/create/update. However, there is no direct get_issue by key, no delete operations for issues/comments/worklogs/attachments, and no Confluence space listing, leaving notable gaps that require workarounds.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Connects Jira with Claude, enabling users to search issues, view issue details, update issues, add comments, and retrieve project information through natural language commands.
      1
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude AI to interact with JIRA for project management and issue tracking, supporting JQL queries, comprehensive issue details retrieval with subtasks and linked issues, and release planning analysis.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI assistants like Claude to Jira projects, enabling natural language queries and operations for issue management, project tracking, comments, and workflows through the Jira REST API.
      21,328 npm
      79
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants like Claude to interact with Jira for project management tasks, including issue creation, updates, workflow transitions, and bulk operations.
      4
      MIT