DtJiraMCPServer

MCP Server for Jira Cloud and JSM Cloud administration via natural language.

Overview

dtJiraMCPServer provides a Model Context Protocol (MCP) server that bridges LLM clients (such as Claude Desktop or Claude Code) with Atlassian Jira Cloud and Jira Service Management (JSM) Cloud REST APIs. The server exposes 61 tools across 12 categories, enabling an LLM to perform administrative and operational tasks across both platforms.

Features

• 61 tools across 12 feature areas
• Read-only mode - restrict to non-mutating tools via JIRA_READ_ONLY
• Self-documenting - LLMs can discover tools and read usage guides at runtime
• Robust error handling - structured errors with retry, rate limiting, and backoff
• Input validation - validates parameters before making API calls
• Pagination - consistent pagination across all list operations
• Stateless - no local state or caching; designed for containerised deployment

Tool Categories

See docs/tool-reference.md for the complete tool listing.

Quick Start

Docker (Recommended)

docker build -t dtjiramcpserver:latest .

docker run -i --rm \
  --read-only \
  -v dtjiramcp_data:/_working \
  --security-opt=no-new-privileges \
  --cap-drop=ALL \
  -e JIRA_INSTANCE_URL=https://your-domain.atlassian.net \
  -e [email protected] \
  -e JIRA_API_TOKEN=your-api-token \
  dtjiramcpserver:latest

Local Development

git clone <repo-url>
cd dtJiraMCPServer
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS
pip install -e ".[dev]"

export JIRA_INSTANCE_URL=https://your-domain.atlassian.net
export [email protected]
export JIRA_API_TOKEN=your-api-token
python -m dtjiramcpserver

See docs/installation.md for detailed setup instructions.

Environment Variables

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--read-only",
        "-v", "dtjiramcp_data:/_working",
        "--security-opt=no-new-privileges",
        "--cap-drop=ALL",
        "-e", "JIRA_INSTANCE_URL=https://your-domain.atlassian.net",
        "-e", "[email protected]",
        "-e", "JIRA_API_TOKEN=your-api-token",
        "dtjiramcpserver:latest"
      ]
    }
  }
}

Claude Code

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "dtjiramcpserver"],
      "env": {
        "JIRA_INSTANCE_URL": "https://your-domain.atlassian.net",
        "JIRA_USER_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Testing

# Unit tests
pytest tests/unit/ -v --cov=dtjiramcpserver

# Integration tests (require Jira credentials)
export JIRA_INSTANCE_URL=https://your-domain.atlassian.net
export [email protected]
export JIRA_API_TOKEN=your-api-token
pytest tests/integration/ -v

See tests/README.md for test suite documentation.

Documentation

• Installation Guide - Setup and configuration
• User Guide - How the LLM interacts with tools
• Tool Reference - Complete tool listing and parameters

Architecture

• Transport: stdio (MCP SDK native)
• Client layer: httpx-based async HTTP with rate limiting and retry
• Tool framework: Auto-discovery registry with structured error handling
• Application: dtPyAppFramework one-shot pattern

Requirements

• Python 3.10+
• Atlassian Cloud instance with API token access
• Docker (for containerised deployment)

Licence

MIT