workos-jira-mcp-server 1.0.1

MCP server for Jira project management — create issues, search with JQL, manage workflows, and track sprints.

Jira MCP Server

A production-ready Model Context Protocol (MCP) server for Jira project management. Connect any AI agent to Jira — create issues, search with JQL, manage workflows, track sprints, and more.

This is an independent, generalized MCP server. It is not tied to any specific project and can be connected to any AI agent that supports MCP (Claude Desktop, Cursor, WorkOS, or custom agents).

Features

• 🎫 Issues: Create, read, update, search, and transition issues
• 🔍 JQL Search: Full Jira Query Language support
• 🔄 Workflows: Transition issues through statuses (To Do → In Progress → Done)
• 💬 Comments: Add comments to issues
• 📋 Projects: List accessible projects
• 🏃 Sprints: List sprints and get board details

Installation

Recommended — no pre-install required (uses uv):

# uv manages a temporary isolated environment automatically
uvx --from workos-jira-mcp-server jira-mcp-server

Or install permanently with pip:

pip install workos-jira-mcp-server

Or install from source:

git clone https://github.com/workos/workos-jira-mcp-server
cd workos-jira-mcp-server
pip install -e .

Quick Start

export JIRA_BASE_URL="https://your-org.atlassian.net"
export JIRA_EMAIL="[e-mail]"
export JIRA_API_TOKEN="your-api-token"

# Recommended: run via uvx (no install needed)
uvx --from workos-jira-mcp-server jira-mcp-server

# Or if installed via pip
jira-mcp-server

# Or run as a Python module
python -m jira_mcp_server

Configuration

Environment Variables

Variable	Required	Description
JIRA_BASE_URL	✅ Yes	Jira instance URL (e.g., https://your-org.atlassian.net)
JIRA_EMAIL	✅ Yes	Email for Jira authentication
JIRA_API_TOKEN	✅ Yes	API token (generate here)

Getting a Jira API Token

1. Go to Atlassian API Tokens
2. Click Create API token
3. Give it a label and click Create
4. Copy the token

Connecting to AI Agents

Note: Use uvx --from workos-jira-mcp-server jira-mcp-server in all configs below. The --from flag is needed because the PyPI package name (workos-jira-mcp-server) differs from the CLI entry point (jira-mcp-server). You must have uv installed (brew install uv on macOS).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[e-mail]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Alternative — if you have installed via pip install workos-jira-mcp-server and prefer not to use uvx, use the full absolute path to the binary instead:

{ "command": "/path/to/your/bin/jira-mcp-server" }

Find the path with: which jira-mcp-server

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[e-mail]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

VS Code (GitHub Copilot / MCP extension)

Edit .vscode/mcp.json in your project:

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "${input:jiraBaseUrl}",
        "JIRA_EMAIL": "${input:jiraEmail}",
        "JIRA_API_TOKEN": "${input:jiraToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "jiraBaseUrl",
      "type": "promptString",
      "description": "Jira Site URL (e.g., https://your-org.atlassian.net)"
    },
    {
      "id": "jiraEmail",
      "type": "promptString",
      "description": "Jira account email"
    },
    {
      "id": "jiraToken",
      "type": "promptString",
      "description": "Jira API Token",
      "password": true
    }
  ]
}

WorkOS / Custom Agents

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "jira": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["--from", "workos-jira-mcp-server", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "${JIRA_BASE_URL}",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

Available Tools (9)

Tool	Description
jira_get_issue	Get a Jira issue by key
jira_create_issue	Create a new issue
jira_update_issue	Update fields on an existing issue
jira_search_issues	Search issues using JQL
jira_transition_issue	Transition an issue to a new status
jira_add_comment	Add a comment to an issue
jira_list_projects	List all accessible projects
jira_list_sprints	List sprints for a board
jira_get_board	Get board details

Development

git clone https://github.com/workos/workos-jira-mcp-server
cd workos-jira-mcp-server
pip install -e .

# Run tests
pytest

# Run the server locally
JIRA_BASE_URL=https://test.atlassian.net JIRA_EMAIL=[e-mail] JIRA_API_TOKEN=test python -m jira_mcp_server

Publishing

To PyPI

pip install build twine
rm -rf dist/ build/ src/*.egg-info
python -m build
pip install "packaging>=24.2"   # required for Metadata 2.4 support in twine
twine check dist/*              # validate before uploading
twine upload dist/*

To MCP Registry

mcp-publisher login github
mcp-publisher publish

License

MIT — see LICENSE for details.