Skip to main content
Glama
xcollantes

Jira MCP

by xcollantes
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Jira MCP

Jira MCP - The most feature-rich MCP server for Jira

Claude Demo

Python MCP pytest ruff uv CI License Version

The most powerful and feature-rich MCP server for Jira integration. Control Jira through AI-powered LLM clients like Cursor, Claude Desktop, Windsurf, and ChatGPT using the Model Context Protocol.

Why Jira MCP is the Best Choice

  • Enterprise Ready: Runs completely locally with no third-party data sharing. Safe for corporate environments.

  • Full-Featured: Complete Jira control including create, update, search, transition, and manage tickets using natural language.

  • Easy Setup: Pre-built binaries for Linux, macOS, and Windows. Get started in minutes.

  • Actively Maintained: Open source, MIT licensed, with regular updates and community support.

  • AI-Native: Built specifically for the Model Context Protocol to provide the best AI-to-Jira experience.

Related MCP server: Atlassian MCP Server

Getting started

Jira MCP Server

Installation

Install jira-cli

The MCP server uses the jira-cli to execute Jira commands.

Follow the installation instructions for your operating system: https://github.com/ankitpokhrel/jira-cli?tab=readme-ov-file#installation

Get Jira API Token

Depending on your implementation of Jira (Cloud or Self-Hosted), you will need to use a different authentication type.

Get your API token from: https://id.atlassian.com/manage-profile/security/api-tokens

You will need to set the following environment variables:

  • JIRA_API_TOKEN - Your Jira API token

  • JIRA_AUTH_TYPE - Authentication type (bearer for token, basic for Jira account API token, password for Jira account password)

Recommended: Pass these variables in your MCP client configuration using the env field (shown in the configuration examples below). This is more reliable than shell environment variables because GUI applications like Cursor and Windsurf do not inherit variables from .bashrc or .zshrc.

Other ways to add credentials to your environment: https://github.com/ankitpokhrel/jira-cli/discussions/356

Start Jira CLI

jira init

This should initialize the Jira CLI by asking for your Jira URL and credentials.

Test Jira CLI

jira issue list

This should return a list of issues in Jira.

MCP Server: Option 1: Download binaries (Recommended)

Download the latest release for your operating system from the Releases page.

Operating System

Binary

Linux

jira-mcp-linux

Windows

jira-mcp-windows.exe

macOS (Apple Silicon)

jira-mcp-macos-apple-silicon-arm64

macOS (Intel)

jira-mcp-macos-x64

Linux

# Download the binary
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-linux

# Make it executable
chmod +x jira-mcp

# Move to a directory in your PATH (optional)
sudo mv jira-mcp /usr/local/bin/

Add to your LLM client configuration:

NOTE: Make sure to replace /usr/local/bin/jira-mcp with the path to the binary on your machine if you moved it to a different location.

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp",
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

macOS

# For Apple Silicon (M1/M2/M3)
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-macos-apple-silicon-arm64

# For Intel Macs
curl -L -o jira-mcp https://github.com/xcollantes/jira-mcp/releases/latest/download/jira-mcp-macos-x64

# Make it executable
chmod +x jira-mcp

# Move to a directory in your PATH (optional)
sudo mv jira-mcp /usr/local/bin/

Note: macOS may block the binary on first run. If you see a security warning, go to System Settings > Privacy & Security and click Allow Anyway, or run:

xattr -d com.apple.quarantine /usr/local/bin/jira-mcp

Add to your LLM client configuration:

NOTE: Make sure to replace /usr/local/bin/jira-mcp with the path to the binary on your machine if you moved it to a different location.

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp",
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

Windows

  1. Download jira-mcp-windows.exe from the Releases page.

  2. Move the executable to a convenient location (e.g., C:\Program Files\jira-mcp\).

Add to your LLM client configuration:

{
  "mcpServers": {
    "jira": {
      "command": "C:\\Program Files\\jira-mcp\\jira-mcp-windows.exe",
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

NOTE: Make sure to replace C:\\Program Files\\jira-mcp\\jira-mcp-windows.exe with the path to the binary on your machine if you moved it to a different location.

MCP Server: Option 2: Development setup with uv

Get repo:

git clone https://github.com/xcollantes/jira-mcp.git
cd jira-mcp

Add MCP server to your choice of LLM client:

NOTE: You will need to look up for your specific client on how to add MCPs.

Usually the JSON file for the LLM client will look like this:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/REPO/ROOT",
        "run",
        "python",
        "-m",
        "src.main"
      ],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

This will tell your LLM client application that there's a tool that can be called by calling uv --directory /ABSOLUTE/PATH/TO/REPO run python -m src.main.

Install UV: https://docs.astral.sh/uv/getting-started/installation/

MCP Server: Option 3: Install globally with pipx

# Install pipx if you haven't already
brew install pipx
pipx ensurepath

# Clone and install the MCP server
git clone https://github.com/xcollantes/jira-mcp.git
cd jira-mcp
pipx install -e .

How it works

  1. You enter some questions or prompt to a LLM Client such as the Claude Desktop, Cursor, Windsurf, or ChatGPT.

  2. The client sends your question to the LLM model (Sonnet, Grok, ChatGPT)

  3. LLM analyzes the available tools and decides which one(s) to use

    • The LLM you're using will have a context of the tools and what each tool is meant for in human language.

    • Alternatively without MCPs, you could include in the prompt the endpoints and a description on each endpoint for the LLM to "call on". Then you could copy and paste the text commands into the terminal on your machine.

    • MCPs provide a more deterministic and standardized method on LLM-to-server interactions.

  4. The client executes the chosen tool(s) through the MCP server.

    • The MCP server is either running local on your machine or an endpoint hosting the MCP server remotely.

  5. The results are sent back to LLM.

  6. LLM formulates a natural language response and one or both of the following happen:

    • The response is displayed to you with data from the MCP server

    • Some action is performed using the MCP server

Development

Logging

Do not use print statements for logging. Use the logging module instead. Writing to stdout will corrupt the JSON-RPC messages and break your server.

Pre-commit

This project uses pre-commit to run ruff linting and formatting checks, and pytest tests before each commit.

To set up pre-commit hooks:

uv sync
uv run pre-commit install

Once installed, ruff and pytest will automatically run when you commit. To run checks manually on all files:

uv run pre-commit run --all-files

Docstrings / Tool decorator parameters

MCP.tools decorator parameters are especially important as this is the human readable text that the LLM has context of. This will be treated as part of the prompt when fed to the LLM and this will decide when to use each tool.

Architecture

MCP follows a client-server architecture where an MCP host (an AI application like Cursor or ChatGPT desktop) establishes connections to one or more MCP servers. The MCP host accomplishes this by creating one MCP client for each MCP server. Each MCP client maintains a dedicated connection with its corresponding MCP server.

https://modelcontextprotocol.io/docs/learn/architecture

Pitfalls / Troubleshooting

Edit the jira-cli config file

On MacOS:

/Users/<your-username>/.config/.jira/.config.yml

404 error when using jira init

If you get a 404 error when using jira init, you may need to edit the jira-cli config file to point to the correct Jira instance. There are only 3 possible values for the auth type so try each one. basic, password, or bearer.

Available Tools

3 tools
get_alertsGet active weather alerts for a U.S. state.A

Retrieves all currently active weather alerts, warnings, and advisories issued by the National Weather Service for the specified state. This includes severe weather warnings, flood advisories, winter weather alerts, and more.

ParametersJSON Schema
NameRequiredDescriptionDefault
stateYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the source (National Weather Service) and types of alerts included, but does not cover important aspects such as rate limits, authentication needs, data freshness, or error handling, leaving significant gaps for a tool that fetches real-time data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by additional context in the second sentence. Both sentences are efficient and contribute meaning, with no redundant or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 parameter) and the presence of an output schema, the description is reasonably complete. It covers the purpose and scope adequately, though it lacks behavioral details like rate limits or error handling, which are somewhat mitigated by the output schema handling return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema provides no parameter details. The description adds value by specifying that the 'state' parameter refers to a U.S. state, but it does not elaborate on format (e.g., abbreviations vs. full names) or constraints, only partially compensating for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('retrieves'), resource ('active weather alerts, warnings, and advisories'), and scope ('for the specified state'), distinguishing it from sibling tools like get_forecast and get_weather by focusing on alerts rather than forecasts or general weather data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving active weather alerts in a U.S. state, but it does not explicitly state when to use this tool versus alternatives like get_forecast or get_weather, nor does it provide exclusions or prerequisites for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_forecastGet detailed weather forecast for a specific location.A

Retrieves a multi-period weather forecast from the National Weather Service for the specified coordinates. The forecast includes temperature, wind conditions, and detailed descriptions for the next 5 forecast periods (typically covering the next 2-3 days).

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes
longitudeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the data source (National Weather Service), forecast duration (next 5 periods covering 2-3 days), and included elements (temperature, wind conditions, descriptions). However, it doesn't mention rate limits, authentication needs, error conditions, or response format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that are front-loaded with the core purpose and efficiently detail scope and content. Every phrase adds value without redundancy or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 required parameters, no annotations, but with output schema), the description provides good coverage of purpose, data source, and forecast content. The existence of an output schema reduces the need to explain return values, but more behavioral context (like rate limits) would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It specifies that parameters are 'coordinates' and implies they're used for location-based forecasting, adding meaning beyond the bare schema. However, it doesn't clarify coordinate format (e.g., decimal degrees) or range constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('retrieves'), resource ('multi-period weather forecast from the National Weather Service'), and scope ('for the specified coordinates'). It distinguishes from potential siblings by specifying it provides a detailed forecast rather than alerts or current weather.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by specifying 'for the specified coordinates' and mentioning 'detailed forecast,' but doesn't explicitly state when to use this tool versus the 'get_alerts' or 'get_weather' siblings. No explicit alternatives or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_weatherGet weather forecast data for a location.A

Retrieves weather forecast information from the National Weather Service API for the specified location. The location should be in the format of latitude,longitude (e.g., '47.7623,-122.2054').

ParametersJSON Schema
NameRequiredDescriptionDefault
locationYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a retrieval operation from an external API, implying it's likely read-only and non-destructive. However, it doesn't mention potential rate limits, authentication needs, error conditions, or what specific forecast data is returned (though an output schema exists). For a tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise and well-structured in two sentences. The first sentence states the core purpose and source. The second sentence provides the critical parameter format requirement with an example. Every word earns its place with no redundancy or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, external API call) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the purpose and parameter format adequately. The main gap is the lack of sibling tool differentiation, but overall it provides sufficient context for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds crucial meaning beyond the input schema. The schema only shows a 'location' parameter with type 'string' and 0% description coverage. The description specifies the required format ('latitude,longitude') and provides an example ('47.7623,-122.2054'), which is essential for correct usage. This fully compensates for the schema's lack of parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Retrieves weather forecast information from the National Weather Service API for the specified location.' It specifies the verb ('retrieves'), resource ('weather forecast information'), and source ('National Weather Service API'). However, it doesn't explicitly distinguish this tool from its sibling tools (get_alerts, get_forecast), which likely provide related but different weather data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (get_alerts, get_forecast). It mentions the location format requirement, but this is more about parameter semantics than usage context. There's no indication of alternatives, prerequisites, or exclusions for this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation2/5

The tools have significant overlap and ambiguity, as 'get_forecast' and 'get_weather' both retrieve weather forecasts from the National Weather Service for specified locations, making them easily confused. Only 'get_alerts' has a clearly distinct purpose focused on active alerts and warnings, but the other two tools lack clear boundaries.

Naming Consistency5/5

All tool names follow a consistent 'verb_noun' pattern with 'get_' prefix and snake_case formatting, making them predictable and readable. There are no deviations in naming conventions across the three tools.

Tool Count2/5

With only 3 tools, the set feels too thin for a server named 'Jira MCP', which suggests a project management or issue-tracking domain, but the tools are all weather-related. This is an extreme mismatch between the server name and the tool scope, indicating poor appropriateness.

Completeness1/5

The tool surface is severely incomplete for the inferred domain from the server name 'Jira MCP', which should cover Jira-related operations like issues, projects, or workflows. Instead, it only provides weather data retrieval with no CRUD or lifecycle coverage for Jira, leaving obvious gaps that will cause agent failures.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xcollantes/jira-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server