Jira MCP Server
Provides comprehensive issue management, project tracking, and team collaboration capabilities for Jira Cloud, including searching issues with JQL, creating and updating issues, managing comments, handling workflow transitions, and accessing project information.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Jira MCP Server show me all high priority bugs assigned to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-dotenv3. Jira API Setup
Generate an API Token:
Click "Create API token"
Give it a name (e.g., "MCP Server")
Copy the generated token (save it somewhere safe!)
Create Environment Configuration:
# Copy the example environment file cp .env.example .envEdit the
.envfile: Open the.envfile 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_hereImportant: 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.pyThis 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
Create the Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonAdd 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:
pwdExample 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 with JQL or simple filters |
| Get detailed information about a specific issue |
| Get issues assigned to you |
| Create new issues (Stories, Bugs, Tasks) |
| Update issue status, assignee, priority, summary |
| Add comments to issues |
| List all accessible projects |
| Get detailed project information |
Configuration Options ⚙️
Environment Variables
Variable | Description | Required |
| Your Jira Cloud URL (e.g., https://company.atlassian.net) | Yes |
| Your Jira account email | Yes |
| 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
"Missing required environment variables"
Ensure your
.envfile exists and contains all required variablesCheck that variable names match exactly (case-sensitive)
"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)
"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
"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
.envfile to version controlPermissions: 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:
Add new tool functions using the
@mcp.tool()decoratorFollow the existing error handling patterns
Update this README with new functionality
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 toolsadd_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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Manage projects, tasks, time tracking, and team collaboration through natural language.
Manage Jensi projects, tasks, sprints and the AI suggestion inbox from your AI assistant.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.12611 npm8MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT
- AlicenseAqualityNot gradedmaintenanceEnables AI assistants to interact with Atlassian Jira Cloud, allowing users to manage projects, issues, comments, and workflows through natural language commands.61,667 npm3-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-