JIRA MCP Server per Claude Code

Server MCP che espone le operazioni JIRA a Claude Code, pensato per reti aziendali (es. Enel intranet).

Prerequisiti

• Node.js 18+
• Accesso a jira.springlab.enel.com dalla macchina
• Personal Access Token JIRA (PAT)

Installazione

# 1. Installa le dipendenze
npm install

# 2. Crea il file .env dalla copia di esempio
copy .env.example .env

# 3. Modifica .env con il tuo token e URL
notepad .env

# 4. Compila TypeScript
npm run build

Configurazione .env

JIRA_BASE_URL=https://jira.springlab.enel.com
JIRA_TOKEN=il_tuo_pat_qui
JIRA_API_VERSION=2

Come ottenere il PAT: JIRA → click sul tuo avatar → Profilo → Sicurezza → Token di accesso personale → Crea token

Configurazione Claude Code

Opzione A — Configurazione locale al progetto (.mcp.json)

Il file .mcp.json è già presente nella root. Quando lanci claude da questa cartella, viene rilevato automaticamente.

Verifica che il percorso cwd nel file corrisponda alla tua installazione:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "C:\\VSCWorkspace\\Progetti\\jiraMCP"
    }
  }
}

Opzione B — Configurazione globale (~/.claude/mcp.json)

Aggiunge il server a tutte le sessioni Claude Code:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\VSCWorkspace\\Progetti\\jiraMCP\\dist\\index.js"]
    }
  }
}

Opzione C — Estensione VS Code Claude Code

Nell'estensione apri i settings MCP e aggiungi la stessa configurazione dell'Opzione B.

Avvio manuale (debug)

# Modalità sviluppo (senza build)
npm run dev

# Modalità produzione
npm start

Interfaccia Web Locale (senza VS Code)

Puoi usare una UI minimale da browser per invocare i tool MCP.

# 1) Build del server MCP
npm run build

# 2) Avvio UI locale
npm run ui

Apri poi: http://127.0.0.1:8787

Endpoint disponibili:

• GET /api/tools -> lista tool disponibili
• POST /api/call -> invoca un tool ({ "name": "...", "arguments": { ... } })
• POST /api/nl-call -> prompt naturale + traduzione AI ({ "prompt": "...", "execute": true })
• POST /api/restart -> riavvia il processo MCP usato dalla UI

Variabili opzionali:

• MCP_UI_HOST (default: 127.0.0.1)
• MCP_UI_PORT (default: 8787)

Per la modalità linguaggio naturale (AI):

• NL_AI_API_KEY (obbligatoria)
• NL_AI_MODEL (default: gpt-4o-mini)
• NL_AI_BASE_URL (default: https://api.openai.com/v1)

Esempio .env:

NL_AI_API_KEY=sk-...
NL_AI_MODEL=gpt-4o-mini
NL_AI_BASE_URL=https://api.openai.com/v1

Strumenti disponibili

Tool	Descrizione
jira_search	Cerca issue con query JQL
jira_get_issue	Dettagli completi di una issue
jira_create_issue	Crea una nuova issue
jira_update_issue	Aggiorna campi di una issue
jira_add_comment	Aggiungi commento
jira_get_transitions	Elenca transizioni di stato disponibili
jira_transition_issue	Cambia stato a una issue
jira_get_projects	Lista progetti accessibili
jira_assign_issue	Assegna issue a un utente
jira_get_issue_comments	Leggi commenti di una issue

Esempi di utilizzo in Claude Code

# Cerca bug aperti
"cerca le issue con JQL: project = MYPROJ AND issuetype = Bug AND status != Done"

# Crea una task
"crea una task nel progetto ABC con titolo 'Aggiornare documentazione API'"

# Aggiorna stato
"porta la issue ABC-123 in Done"

# Aggiungi commento
"aggiungi un commento a ABC-456: 'Fix verificato in staging'"

Struttura progetto

jiraMCP/
├── src/
│   └── index.ts          # MCP server principale
├── dist/                 # Output compilato (generato da npm run build)
├── .env                  # Le tue credenziali (NON committare!)
├── .env.example          # Template variabili d'ambiente
├── .mcp.json             # Config MCP per Claude Code (progetto locale)
├── package.json
└── tsconfig.json

Sicurezza

• Il file .env non deve mai essere committato (aggiunto al .gitignore)
• Il token transita solo su connessioni interne verso JIRA
• Nessun dato viene inviato a server esterni