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

Category	Tools	Description
Meta	2	Tool discovery and usage guides
Issues	7	JQL search, issue CRUD, transitions
Service Desk	10	Desks, queues, customers, organisations
Request Types	6	Request type CRUD, fields, groups
Fields	10	Custom fields, contexts, screens, screen schemes
Workflows	8	Workflows, statuses, transitions
Knowledge Base	1	Article search
SLA	2	SLA metrics and detail
Assets	1	Workspace queries
Projects	5	Project CRUD operations
Lookup	3	Issue types, priorities, user search
Groups	6	Group CRUD, membership management

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 JIRA_USER_EMAIL=user@example.com \
  -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 JIRA_USER_EMAIL=user@example.com
export JIRA_API_TOKEN=your-api-token
python -m dtjiramcpserver

See docs/installation.md for detailed setup instructions.

Environment Variables

Variable	Purpose	Required	Default
JIRA_INSTANCE_URL	Atlassian Cloud instance URL	Yes	-
JIRA_USER_EMAIL	Atlassian account email	Yes	-
JIRA_API_TOKEN	Atlassian API token	Yes	-
JIRA_READ_ONLY	Restrict to read-only tools (true/1/yes)	No	false
LOG_LEVEL	Application log level	No	INFO

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", "JIRA_USER_EMAIL=user@example.com",
        "-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": "user@example.com",
        "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 JIRA_USER_EMAIL=user@example.com
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