MCP JIRA Server

The MCP JIRA Server lets AI tools create and manage JIRA issues by handling markdown-to-ADF conversion, flexible field mappings, and multi-site configurations. It enables seamless integration with JIRA REST API v3, so you can generate well-formatted issues directly from your AI workflows and automation pipelines.

How to use

You connect an MCP client to the MCP JIRA Server and issue high-level actions like creating or updating JIRA issues, or searching for issues with JQL. You provide inputs such as the project key, issue type, summary, and a markdown description. The server automatically converts the markdown to Atlassian Document Format (ADF), maps fields to standard or custom JIRA fields, and resolves assignee emails to the correct accountId. Use the multi-site support to target different JIRA instances by selecting the appropriate site alias in your request.

Typical usage patterns include creating new issues with rich, formatted descriptions, updating existing issues with new details, and performing JQL searches to retrieve issue data. If you supply optional fields like labels, priority, or due dates through additional fields, the server includes them in the request. If certain fields aren’t available in your JIRA configuration, the server gracefully excludes them and proceeds with the available ones.

To work with multiple JIRA sites, configure each site with its URL, authentication credentials (email and API token), and a site alias. In your requests, specify the site alias to target the correct JIRA instance.

How to install

Prerequisites: you need Python 3.11 or later and internet access to reach your JIRA instances. You also need a working MCP runtime environment to execute MCP servers.

Step-by-step setup using uvx (recommended for ephemeral environments):

Install UV (if not already installed):

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Configure JIRA settings via web UI (opens in your browser)
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# This launches a configuration interface at http://localhost:8501

Configuration and operation notes

Configuration is loaded from a YAML file named config.yaml. You can specify multiple JIRA sites with aliases, and designate a default site. The file includes fields for the site URL, email, API token, and whether the site is a cloud instance. You can adjust logging level and file paths in this file as well.

Security and troubleshooting notes

Use a dedicated API token for each JIRA site, and keep it secret. If you encounter authentication issues, verify that the email matches the JIRA account and the API token is current. For field-related problems, supply additional_fields for optional or custom fields and verify their availability in your JIRA configuration. When markdown conversion encounters complex formatting, ensure fenced code blocks specify a supported language and that tables render correctly in JIRA.

Available tools and endpoints described in this server

create_jira_issue — Create a new JIRA issue with standard fields (project, summary, description, issue type) and optional additional fields. The description supports markdown that will be converted to ADF.

update_jira_issue — Update existing issues, changing fields such as summary, description (markdown supported), assignee, or custom fields. Only supplied fields are updated.

search_jira_issues — Query JIRA issues with JQL. You can request full data or a lighter subset with basic_only. Supports site_alias for multi-site configurations.

Troubleshooting quick references

Common issues include authentication errors, field availability, markdown conversion, and connection problems. Start by validating your API tokens and URLs, ensure the JIRA REST API v3 is reachable, and review your config.yaml for site aliases and field mappings.

Configuration

The server uses a config.yaml to define multi-site JIRA connections. Each site entry includes the URL, user email, API token, and cloud flag. You can also configure logging behavior, such as log_level, log_file_path, and rotation settings. Key example values appear below.

name: "My Company JIRA Integration"
log_level: "INFO"
default_site_alias: "prod_jira"

sites:
  prod_jira:
    url: "https://mycompany.atlassian.net"
    email: "automation-user@mycompany.com"
    api_token: "abc123xyz789efg_your_token_here_jkl"
    cloud: true

  dev_jira:
    url: "https://dev-mycompany.atlassian.net"
    email: "dev-automation@mycompany.com"
    api_token: "another_token_for_dev_environment"
    cloud: true

Available tools

create_jira_issue

Create a new JIRA issue with standard fields (project, summary, description) and optional additional fields. Supports markdown description that is converted to ADF.

update_jira_issue

Update existing JIRA issues by modifying provided fields. Only fields included in the request are changed.

search_jira_issues

Search for JIRA issues using JQL. Optional site_alias selects the target site; basic_only can reduce payload for performance.