JIRA MCP Server

An AI-friendly JIRA integration server using the Model Context Protocol (MCP). This server provides semantic tools for searching, retrieving, and interacting with JIRA issues without requiring knowledge of JQL or JIRA internals.

✨ Features

• 🤖 AI-Friendly Interface: Uses semantic parameters instead of JQL
• 🔄 Automatic JIRA Detection: Leverages gouqi 0.14.0 for Cloud/Server detection
• ⚡ Smart Caching: Metadata caching with TTL for performance
• 🛠️ Comprehensive Tools: Search, issue details, user issues
• 🚦 Error Handling: MCP-compliant error codes and messages
• 🔐 Flexible Authentication: Supports PAT, Basic, Bearer, and Anonymous auth

🚀 Quick Start

Prerequisites

• Rust 1.75.0 or later
• Access to a JIRA instance (Cloud or Server)
• JIRA authentication credentials

1. Configuration

Set up your JIRA connection using environment variables:

# Required: JIRA instance URL
export JIRA_URL="https://your-company.atlassian.net"

# Required: Authentication
export JIRA_AUTH_TYPE="pat"  # or "basic", "bearer", "anonymous"
export JIRA_TOKEN="your_personal_access_token"

# Optional: Advanced settings
export JIRA_CACHE_TTL="300"        # Cache TTL in seconds (default: 300)
export JIRA_MAX_RESULTS="50"       # Max search results (default: 50, max: 200)
export JIRA_REQUEST_TIMEOUT="30"   # Request timeout in seconds (default: 30)

2. Build and Run

# Clone and build
git clone https://github.com/yourusername/gouqi-mcp-server.git
cd gouqi-mcp-server
cargo build --release

# Run the server
./target/release/jira-mcp-server

3. Test Connection

# Test tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./target/debug/jira-mcp-server

# Test connection
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"test_connection","arguments":{}}}' | ./target/debug/jira-mcp-server

🛠️ Available Tools

search_issues

Search for JIRA issues using AI-friendly semantic parameters.

Example Usage:

{
  "issue_types": ["story", "bug"],
  "assigned_to": "me",
  "status": ["open", "in_progress"],
  "project_key": "PROJ",
  "created_after": "7 days ago",
  "limit": 25
}

get_issue_details

Get detailed information about a specific JIRA issue.

Example Usage:

{
  "issue_key": "PROJ-123",
  "include_comments": true,
  "include_attachments": true
}

get_user_issues

Get issues assigned to a specific user with filtering options.

Example Usage:

{
  "username": "me",
  "status_filter": ["open", "in_progress"],
  "issue_types": ["story", "bug"],
  "due_date_filter": "overdue"
}

get_server_status

Get server status and JIRA connection information.

test_connection

Test JIRA connection and authentication.

clear_cache

Clear all cached metadata.

📁 Project Structure

jira-mcp-server/
├── Cargo.toml                    # Package configuration
├── src/
│   ├── main.rs                   # Server entry point
│   ├── lib.rs                    # Main server implementation
│   ├── config.rs                 # Configuration management
│   ├── cache.rs                  # Metadata caching
│   ├── jira_client.rs            # JIRA API wrapper
│   ├── semantic_mapping.rs       # AI-friendly parameter mapping
│   ├── error.rs                  # Error types and handling
│   └── tools/                    # MCP tool implementations
│       ├── mod.rs
│       ├── search_issues.rs
│       ├── issue_details.rs
│       └── user_issues.rs
├── config/
│   └── jira-mcp-config.toml.example  # Configuration example
└── README.md

⚙️ Configuration

Environment Variables (Recommended)

# Required
JIRA_URL="https://your-instance.atlassian.net"
JIRA_AUTH_TYPE="pat"  # "pat", "basic", "bearer", "anonymous"
JIRA_TOKEN="your_token"

# For Basic Auth
JIRA_USERNAME="your_username"
JIRA_PASSWORD="your_password"  # pragma: allowlist secret

# Optional
JIR

... [View full README on GitHub](https://github.com/wunderfrucht/gouqi-mcp-server#readme)