AI-Powered Jira MCP Server

A Model Context Protocol (MCP) server for Jira integration powered by Claude AI. This server enables natural language interactions with Jira, allowing you to create issues, manage boards, search tickets, and more using conversational AI.

Features

Core Capabilities

• Natural Language Processing: Interact with Jira using plain English
• Issue Management: Create, update, search, and transition issues
• Board Management: Create and manage Scrum/Kanban boards
• Comment System: Add comments to issues
• User Management: Assign users and manage permissions
• Image Analysis: Upload images and get AI-powered descriptions
• Smart Field Detection: AI asks for missing required fields
• Conversation Context: Multi-turn conversations with session management

Supported Operations

1. Issue Operations

   • Create issues with detailed descriptions
   • Update existing issues
   • Search issues (natural language or JQL)
   • Transition issues through workflow
   • Add comments
   • Attach files/images

2. Board Operations

   • Create new boards (Scrum/Kanban)
   • List all boards
   • Get board details

3. Project Operations

   • List all projects
   • Get project details
   • Get assignable users

Installation

Prerequisites

• Python 3.9+
• Jira account with API access
• Anthropic API key

Setup

1. Clone the repository

git clone <your-repo>
cd mcp_server

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

cp .env.example .env

Edit .env with your credentials:

JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token
ANTHROPIC_API_KEY=your-anthropic-api-key

4. Get Jira API Token

   • Go to https://id.atlassian.com/manage-profile/security/api-tokens
   • Click "Create API token"
   • Copy the token to your .env file

5. Get Anthropic API Key

   • Go to https://console.anthropic.com/
   • Create an API key
   • Copy to your .env file

Usage

Start the Server

python server.py

The server will start on http://localhost:8000

API Documentation

Once running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Example Requests

1. Natural Language Chat

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a bug issue about login failure on mobile app",
    "session_id": "test-session-1"
  }'

Response:

{
  "session_id": "test-session-1",
  "response": "I'd be happy to help create a bug issue. Which project should I create this in? Please provide the project key (e.g., PROJ, DEV, etc.)",
  "tool_calls": [],
  "success": true
}

2. Follow-up Message

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create it in MOBILE project",
    "session_id": "test-session-1"
  }'

3. Create Issue Directly

curl -X POST http://localhost:8000/issues/create \
  -H "Content-Type: application/json" \
  -d '{
    "project_key": "PROJ",
    "summary": "Login button not working",
    "description": "Users cannot click the login button on iOS devices",
    "issue_type": "Bug",
    "priority": "High"
  }'

4. Upload Image

curl -X POST http://localhost:8000/upload \
  -F "file=@screenshot.png"

Response includes AI analysis:

{
  "file_id": "123e4567-e89b-12d3-a456-426614174000",
  "filename": "screenshot.png",
  "path": "./storage/uploads/123e4567-e89b-12d3-a456-426614174000.png",
  "analysis": "The image shows a mobile login screen with a disabled login button...",
  "success": true
}

5. Search Issues

curl -X POST http://localhost:8000/issues/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find all high priority bugs assigned to me",
    "max_results": 20
  }'

6. Get Boards

curl -X GET http://localhost:8000/boards

7. Get Projects

curl -X GET http://localhost:8000/projects

Natural Language Examples

The AI can understand various ways of expressing commands:

Creating Issues

• "Create a bug issue about the login page crashing"
• "Add a new task for implementing dark mode"
• "I need to report a critical issue with payment processing"
• "Make a story for user authentication feature"

Searching

• "Show me all my open tasks"
• "Find bugs in the MOBILE project"
• "What issues are due this week?"
• "List all high priority items"

Updating

• "Change PROJ-123 status to In Progress"
• "Assign PROJ-456 to john.doe"
• "Update the description of PROJ-789"
• "Add a comment to PROJ-123 saying it's fixed"

Board Management

• "Create a new scrum board for the API project"
• "Show me all available boards"
• "List projects I have access to"

Architecture

┌─────────────┐
│   Client    │
│   (UI/CLI)  │
└──────┬──────┘
       │
       │ HTTP/REST
       │
┌──────▼──────────────────────────────────┐
│          FastAPI Server                  │
│  ┌────────────────────────────────────┐ │
│  │     LLM Orchestrator (Claude)      │ │
│  │  - Natural Language Processing     │ │
│  │  - Tool Selection & Execution      │ │
│  │  - Conversation Management         │ │
│  └─────────┬──────────────────────────┘ │
│            │                             │
│  ┌─────────▼──────────┐                 │
│  │     MCP Tools      │                 │
│  │  - Tool Registry   │                 │
│  │  - Tool Execution  │                 │
│  └─────────┬──────────┘                 │
│            │                             │
│  ┌─────────▼──────────┐                 │
│  │   Jira Client      │                 │
│  │  - API Wrapper     │                 │
│  │  - Authentication  │                 │
│  └─────────┬──────────┘                 │
└────────────┼──────────────────────────────┘
             │
             │ Jira REST API
             │
    ┌────────▼────────┐
    │   Jira Cloud    │
    │   (Atlassian)   │
    └─────────────────┘

Project Structure

/mcp_server
  /tools              # MCP tool definitions and handlers
  /schemas            # Pydantic models for API requests/responses
  /jira_client        # Jira API client wrapper
  /llm_orchestrator   # Claude AI integration and tool orchestration
  /storage