guerchele/jira-dc-mcp repository overview

⁠Jira Data Center MCP Server - Docker Image

Model Context Protocol (MCP) server for Atlassian Jira Data Center with semantic search and AI-powered workflow automation.

Transform natural language queries into precise Jira API operations. Built for LLMs (Claude, GPT-4) to interact intelligently with Jira Data Center.

⁠🚀 Quick Start

⁠Run with Docker

docker run -it \
  -e JIRA_URL=https://jira.example.com \
  -e JIRA_AUTH_METHOD=pat \
  -e JIRA_TOKEN=your-personal-access-token \
  ghcr.io/guerchele/jira-dc-mcp:latest

⁠Run with Docker Compose

Create docker-compose.yml:

version: '3.8'
services:
  jira-mcp:
    image: guerchele/jira-dc-mcp:latest
    environment:
      JIRA_URL: https://jira.example.com
      JIRA_AUTH_METHOD: pat
      JIRA_TOKEN: your-personal-access-token
      LOG_LEVEL: info
    restart: unless-stopped

Then run:

docker-compose up -d

⁠📋 Requirements

• Jira Data Center instance with API access
• Valid credentials: OAuth 2.0, Personal Access Token, OAuth 1.0a, or Basic Auth
• Docker Desktop 4.37.1+ or Docker Engine 20.10+

⁠🔧 Environment Variables

⁠Required

⁠Optional

⁠💡 Usage Examples

⁠Example 1: Basic Container

docker run -it --rm \
  -e JIRA_URL=https://jira.example.com \
  -e JIRA_AUTH_METHOD=pat \
  -e JIRA_TOKEN=abc123xyz \
  guerchele/jira-dc-mcp:latest

⁠Example 2: With Persistent Configuration

docker run -it -d \
  --name jira-mcp \
  -v ~/.jira-mcp:/root/.jira-mcp \
  -e JIRA_URL=https://jira.example.com \
  -e JIRA_AUTH_METHOD=pat \
  -e JIRA_TOKEN=abc123xyz \
  guerchele/jira-dc-mcp:latest

⁠Example 3: Debug Mode

docker run -it --rm \
  -e JIRA_URL=https://jira.example.com \
  -e JIRA_AUTH_METHOD=pat \
  -e JIRA_TOKEN=abc123xyz \
  -e LOG_LEVEL=debug \
  guerchele/jira-dc-mcp:latest

⁠Example 4: Connect from Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira-datacenter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "JIRA_URL=https://jira.example.com",
        "-e",
        "JIRA_AUTH_METHOD=pat",
        "-e",
        "JIRA_TOKEN=your-token",
        "guerchele/jira-dc-mcp:latest"
      ]
    }
  }
}

⁠🏗️ Key Features

✅ Semantic Search Engine - Natural language queries with >90% relevance
✅ Three MCP Tools - search_ids, get_id, call_id
✅ Multi-Authentication - OAuth 2.0, PAT, OAuth 1.0a, Basic Auth
✅ Production Resilient - Circuit breakers, rate limiting, retries
✅ Secure by Default - Non-root user, credential redaction
✅ Multi-Architecture - Supports linux/amd64 and linux/arm64

⁠🔍 MCP Tools Available

1. search_ids - Find Jira operations using natural language

   {"query": "create issue", "limit": 5}
   

   Copy

2. get_id - Get operation details and schema

   {"operation_id": "createIssue"}
   

   Copy

3. call_id - Execute Jira API operations

   {"operation_id": "createIssue", "parameters": {...}}
   

   Copy

⁠🏥 Health Checks

The container includes built-in health checks:

# Check container health status
docker inspect --format='{{.State.Health.Status}}' jira-mcp

# View health check logs
docker logs jira-mcp

⁠🔐 Security Notes

• Credentials are never logged (automatic redaction)
• Runs as non-root user (nodejs, UID 1001)
• Uses OS-native keychains when available
• Supports read-only root filesystem

⁠📖 Full Documentation

• GitHub Repository: https://github.com/guercheLE/jira-dc-mcp⁠
• Docker Guide: docs/docker.md⁠
• Authentication Guide: docs/authentication.md⁠
• Troubleshooting: docs/troubleshooting.md⁠

⁠🐛 Troubleshooting

⁠Container exits immediately

# Check logs for errors
docker logs jira-mcp

Common causes:

• Missing JIRA_URL environment variable
• Invalid authentication credentials
• Network connectivity issues

⁠Health check failing

# Run health check manually
docker exec jira-mcp node /app/dist/healthcheck.js

⁠Cannot connect to Jira

# Test connectivity from container
docker exec jira-mcp wget -O- https://jira.example.com/status

⁠📜 License

LGPL-3.0 License - see LICENSE⁠

⁠🤝 Contributing

Contributions welcome! See CONTRIBUTING.md⁠

Need help? Open an issue on GitHub⁠