home / mcp / jira mcp server

Jira MCP Server

MCP server enabling Jira Cloud issue and project management through MCP clients

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jondoesflow-mcp_server_jira": {
      "command": "/Users/yourusername/.local/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/MCP_Server_JIra",
        "run",
        "jira_server.py"
      ],
      "env": {
        "JIRA_EMAIL": "[email protected]",
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_API_TOKEN": "your_actual_api_token_here"
      }
    }
  }
}

You can run a Jira MCP Server that connects Jira Cloud to your MCP clients, enabling issue and project management directly through Claude and other MCP-enabled tools. This guide gives you practical steps to install, configure, and use the server so you can search, create, and manage Jira issues and projects from your MCP client workflow.

How to use

Use the MCP server to perform common Jira actions from your MCP client: search for issues with JQL or filters, view issue details, create and update issues, add comments, and list or inspect projects. You can assign issues to yourself with natural identifiers like me or myself, and you’ll see status transitions and rich text in Atlassian Document Format when supported by the client.

How to install

Prerequisites you need before starting the server:

Python 3.10 or higher
Claude Desktop installed from claude.ai/download
Access to a Jira Cloud instance
Jira API token

Then install and set up the MCP server using these steps.

# 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

# Test Jira connection before proceeding (optional)
$HOME/.local/bin/uv run test_connection.py
```

Note: The test will verify login, accessible projects, and ability to search issues if your environment is configured correctly.

Configuration and run details

Configure Jira access in your environment. Create and populate an environment file with your Jira Cloud details, then start the MCP server using the MCP runtime.

# Copy the example environment file
cp .env.example .env

# Edit the .env file to include your Jira details
# Your Jira Cloud instance URL (without trailing slash)
JIRA_BASE_URL=https://yourcompany.atlassian.net

# Your Jira account email
[email protected]

# Your Jira API token
JIRA_API_TOKEN=your_actual_api_token_here
```

Important: Replace placeholders with your actual Jira details.

Next, configure Claude Desktop to run the MCP server. The configuration points Claude to a local MCP server process managed by the MCP runtime.

{
  "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 in the project directory:
```
pwd

Test and start the server

Restart Claude Desktop after making changes so the MCP tools become available in the interface.

Optional test to ensure the connection works after configuration:

# Start the MCP server as configured above
$HOME/.local/bin/uv run test_connection.py
```

If tests pass, you can start issuing commands from your MCP client to manage Jira.

Security and maintenance

Keep your Jira API token secure and do not commit your .env file to any shared or public repository. The server respects Jira permissions, and you access only what you have access to in Jira. Use HTTPS Jira URLs to protect data in transit.

If you ever need to change credentials or tokens, update the .env file and restart Claude Desktop to apply the changes.

Troubleshooting and notes

Common issues you might see include missing environment variables, invalid Jira credentials, or workflow restrictions in Jira preventing certain status transitions. Ensure the exact environment variable names are used, the API token is current, and the Jira URL has no trailing slash.

For API checks, you can validate your Jira connection via a direct REST call from your environment as a quick sanity check.

Available tools

search_issues

Search issues using JQL or simple filters to find relevant tickets quickly.

get_issue

Retrieve detailed information about a specific Jira issue, including comments and history.

get_my_issues

Return issues assigned to the authenticated user for quick personal workload view.

create_issue

Create new Jira issues such as Stories, Bugs, or Tasks in a specified project.

update_issue

Update an issue's status, assignee, priority, or summary.

add_comment

Add or attach comments to existing Jira issues.

list_projects

List all projects accessible to the authenticated user.

get_project_info

Get detailed information about a Jira project, including its issue types.