Skip to main content
Glama
Jira MCP Server

Jira MCP Server

by jondoesflow

Jira MCP Server 🎫

A Model Context Protocol (MCP) server that integrates with Jira Cloud to provide comprehensive issue management, project tracking, and team collaboration capabilities directly through Claude and other MCP clients.

Features ✨

Issue Management

  • Search Issues: Advanced JQL-based searching with simple filters

  • Get Issue Details: Comprehensive issue information with comments

  • Create Issues: Create Stories, Bugs, Tasks, and other issue types

  • Update Issues: Change status, assignee, priority, and summary

  • Add Comments: Add comments to existing issues

  • My Issues: Quick access to your assigned tickets

Project Management

  • List Projects: View all accessible projects

  • Project Details: Get comprehensive project information

  • Issue Types: See available issue types per project

Smart Features

  • Flexible User Assignment: Use 'me', 'myself', or actual usernames/emails

  • Status Transitions: Automatically handle Jira workflow transitions

  • Rich Text Support: Handles Atlassian Document Format (ADF)

  • Error Handling: Comprehensive error messages and validation

Related MCP server: Jira MCP

Quick Start 🚀

1. Prerequisites

  • Python 3.10 or higher

  • Claude Desktop - Download and install from claude.ai/download

  • Access to a Jira Cloud instance

  • Jira API token (we'll generate this below)

2. Installation

# Clone this repository
git clone https://github.com/jondoesflow/MCP_Server_JIra.git
cd MCP_Server_JIra

# Install uv (Python package manager) if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Set up virtual environment and install dependencies
$HOME/.local/bin/uv venv
$HOME/.local/bin/uv add "mcp[cli]" httpx python-dotenv

3. Jira API Setup

  1. Generate an API Token:

    • Go to Atlassian Account Security

    • Click "Create API token"

    • Give it a name (e.g., "MCP Server")

    • Copy the generated token (save it somewhere safe!)

  2. Create Environment Configuration:

    # Copy the example environment file
    cp .env.example .env
  3. Edit the .env file: Open the .env file in your text editor and fill in your actual values:

    # Your Jira Cloud instance URL (without trailing slash)
    JIRA_BASE_URL=https://yourcompany.atlassian.net
    
    # Your Jira account email
    JIRA_EMAIL=your.email@company.com
    
    # Your Jira API token (paste the token you generated above)
    JIRA_API_TOKEN=your_actual_api_token_here

    Important: Replace the placeholder values with your actual Jira details!

4. Test Your Connection

# Test your Jira connection before proceeding
$HOME/.local/bin/uv run test_connection.py

This should show:

  • ✅ Successful login to your Jira instance

  • ✅ List of accessible projects

  • ✅ Ability to search for issues

If any tests fail, double-check your .env file values.

5. Configure Claude Desktop

  1. Create the Claude Desktop configuration file:

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add this configuration (replace /ABSOLUTE/PATH/TO/ with your actual path):

    {
      "mcpServers": {
        "jira": {
          "command": "/Users/yourusername/.local/bin/uv",
          "args": [
            "--directory",
            "/ABSOLUTE/PATH/TO/MCP_Server_JIra",
            "run",
            "jira_server.py"
          ]
        }
      }
    }

    To find your absolute path, run this in the project directory:

    pwd
  3. Example configuration (update the username and path):

    {
      "mcpServers": {
        "jira": {
          "command": "/Users/jonathanrussell/.local/bin/uv",
          "args": [
            "--directory",
            "/Users/jonathanrussell/Documents/VIbe/MCP/MCP_Server_JIra",
            "run",
            "jira_server.py"
          ]
        }
      }
    }

6. Restart Claude Desktop

Important: Completely quit and restart Claude Desktop for the changes to take effect. You should then see MCP tools available in the interface.

Usage Examples 💡

Search for Issues

"Show me all high priority bugs in the MOBILE project"
"Find issues assigned to me that are in progress"
"Search for issues with 'login' in the title"

Create Issues

"Create a bug report for the login timeout issue in project WEB"
"Create a story for implementing dark mode, assign it to me"
"Create a task to update documentation with high priority"

Manage Issues

"Move ticket WEB-123 to In Progress"
"Assign ticket MOBILE-456 to john.doe@company.com"
"Add a comment to WEB-123 saying 'Fixed in latest build'"

Project Information

"List all available projects"
"Show me details about the MOBILE project"
"What are my current assigned issues?"

Available Tools 🛠️

Tool

Description

search_issues

Search issues with JQL or simple filters

get_issue

Get detailed information about a specific issue

get_my_issues

Get issues assigned to you

create_issue

Create new issues (Stories, Bugs, Tasks)

update_issue

Update issue status, assignee, priority, summary

add_comment

Add comments to issues

list_projects

List all accessible projects

get_project_info

Get detailed project information

Configuration Options ⚙️

Environment Variables

Variable

Description

Required

JIRA_BASE_URL

Your Jira Cloud URL (e.g., https://company.atlassian.net)

Yes

JIRA_EMAIL

Your Jira account email

Yes

JIRA_API_TOKEN

Your Jira API token

Yes

JQL Examples

The server supports full JQL (Jira Query Language) for advanced searching:

project = "WEB" AND assignee = currentUser() AND status != Done
priority in (High, Highest) AND created >= -7d
issuetype = Bug AND status = "In Progress"
text ~ "login" AND project in (WEB, MOBILE)

Troubleshooting 🔧

Common Issues

  1. "Missing required environment variables"

    • Ensure your .env file exists and contains all required variables

    • Check that variable names match exactly (case-sensitive)

  2. "Jira API error: 401"

    • Verify your email and API token are correct

    • Ensure the API token hasn't expired

    • Check that your Jira URL is correct (no trailing slash)

  3. "User not found" when assigning

    • Use exact email addresses or usernames

    • Try using 'me' to assign to yourself

    • Verify the user has access to the project

  4. "Status not available" when updating

    • Check available transitions with the error message

    • Jira workflows restrict which status changes are allowed

    • Use exact status names (case-sensitive)

Debug Mode

To enable detailed logging, modify the logging level in jira_server.py:

logging.basicConfig(level=logging.DEBUG)

Testing API Connection

You can test your Jira connection independently:

# Test API connection
curl -u "your.email@company.com:your_api_token" \
  -H "Accept: application/json" \
  "https://yourcompany.atlassian.net/rest/api/3/myself"

Security Notes 🔒

  • API Tokens: Never commit your .env file to version control

  • Permissions: The server respects your Jira permissions - you can only access what you normally can

  • Rate Limiting: The server includes basic rate limiting respect for Jira's API limits

  • HTTPS Only: Always use HTTPS Jira URLs for secure communication

Contributing 🤝

This MCP server is designed to be extensible. To add new features:

  1. Add new tool functions using the @mcp.tool() decorator

  2. Follow the existing error handling patterns

  3. Update this README with new functionality

  4. Test thoroughly with your Jira instance

License 📄

This project is open source. Feel free to modify and distribute according to your needs.


Need Help? Check the MCP Documentation or Jira REST API Documentation.

Available Tools

8 tools
add_commentB

Add a comment to a Jira issue.

Args:
    issue_key: The issue key (e.g., 'PROJ-123')
    comment: The comment text to add

Inputs: issue_key (required), comment (required). Returns: result

create_issueB

Create a new Jira issue.

Args:
    project_key: The project key (e.g., 'PROJ')
    summary: Brief description of the issue
    issue_type: Type of issue ('Story', 'Bug', 'Task', etc.)
    description: Detailed description of the issue
    priority: Priority level ('Highest', 'High', 'Medium', 'Low', 'Lowest')
    assignee: Username or email of assignee (leave empty for unassigned)

Inputs: project_key (required), summary (required), issue_type, description, +2 more. Returns: result

get_issueA

Get detailed information about a specific Jira issue.

Args:
    issue_key: The issue key (e.g., 'PROJ-123')

Inputs: issue_key (required). Returns: result

get_my_issuesB

Get issues assigned to the current user.

Args:
    status: Filter by status (e.g., 'To Do', 'In Progress', 'Done')
    max_results: Maximum number of results to return (default: 10)

Inputs: status, max_results. Returns: result

get_project_infoB

Get detailed information about a specific project.

Args:
    project_key: The project key (e.g., 'PROJ')

Inputs: project_key (required). Returns: result

list_projectsB

List all accessible Jira projects.

Inputs: no named parameters. Returns: result

search_issuesA

Search for Jira issues using JQL or simple filters.

Args:
    jql: JQL (Jira Query Language) string for advanced searches
    project: Project key or name to filter by
    assignee: Assignee username, email, or 'currentUser()' for yourself
    status: Status name (e.g., 'To Do', 'In Progress', 'Done')
    issue_type: Issue type (e.g., 'Story', 'Bug', 'Task')
    priority: Priority level (e.g., 'High', 'Medium', 'Low')
    max_results: Maximum number of results to return (default: 20)

Inputs: jql, project, assignee, status, +3 more. Returns: result

update_issueB

Update an existing Jira issue.

Args:
    issue_key: The issue key (e.g., 'PROJ-123')
    status: New status (e.g., 'In Progress', 'Done')
    assignee: New assignee username/email, or 'unassigned' to remove assignee
    priority: New priority ('Highest', 'High', 'Medium', 'Low', 'Lowest')
    summary: New summary/title for the issue

Inputs: issue_key (required), status, assignee, priority, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap. For example, create_issue, get_issue, and update_issue handle different lifecycle stages, while get_my_issues and search_issues serve different query needs. The descriptions reinforce these distinctions, making tool selection unambiguous.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern (e.g., add_comment, create_issue, get_issue). There are no deviations in style or convention, making the set predictable and easy to parse for an agent.

    Tool Count5/5

    With 8 tools, this server is well-scoped for Jira operations, covering core workflows like issue management and project queries. Each tool serves a clear purpose without bloat, aligning with typical server sizes of 3-15 tools.

    Completeness4/5

    The toolset provides strong coverage for Jira's core domain, including CRUD operations for issues and basic project management. A minor gap exists in missing tools for deleting issues or managing comments beyond addition, but agents can work around this with available tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with Jira Cloud instances for comprehensive issue management including creating, updating, searching issues, managing comments, workflow transitions, and project metadata discovery. Supports JQL queries, user search, and custom field operations with secure API token authentication.
      12
      611 npm
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Jira Cloud instances, including creating and updating issues, managing sprints and projects, adding comments, tracking worklogs, and searching with presets.
      4 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Jira Cloud through the REST API, supporting project management, issue operations (create, read, update, delete), JQL search, task assignments, and status transitions.
      -