Jira API
Manage Jira projects, tickets, sprints, and comprehensive productivity metrics through the ConstellationAPI.
Base Path
/jira
Available MCP Tools
The Jira integration provides 24 tools accessible via the MCP protocol.
Tool Summary
| Category | Tools |
|---|---|
| Projects | get_projects, get_project_info, get_available_statuses, get_assignable_users |
| Users | get_users, get_user_by_email, get_tickets_by_user |
| Tickets | get_tickets, get_ticket, create_ticket, update_ticket, get_ticket_comments, add_ticket_comment, get_available_transitions, transition_issue, assign_issue, get_issues_by_status, get_issue_aging, add_issue_labels, remove_issue_labels |
| Metrics | get_developer_metrics, get_dora_metrics, get_sprint_metrics, get_throughput_metrics, get_throughput_metrics_by_project, get_project_productivity_metrics, get_developer_ticket_metrics_all_projects, get_executive_summary_all_projects |
| User Work | get_my_jira_work |
Project Operations
get_projects
List all Jira projects accessible to the user.
Input Schema:
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum number of results"
},
"offset": {
"type": "integer",
"description": "Number of results to skip"
}
},
"required": []
}
Example Request:
curl -X POST http://localhost:3007/mcp/jira/execute \
-H "Content-Type: application/json" \
-H "X-JWT-Token: <your-jwt-token>" \
-d '{
"tool": "get_projects",
"arguments": { "limit": 20 }
}'
Example Response:
{
"success": true,
"data": {
"projects": [
{
"id": "10001",
"key": "PROJ",
"name": "Project Alpha",
"description": "Main project for Alpha team",
"lead": {
"accountId": "abc123def456",
"displayName": "John Doe",
"emailAddress": "john.doe@example.com"
},
"projectTypeKey": "software",
"style": "next-gen",
"url": "https://your-instance.atlassian.net/browse/PROJ"
},
{
"id": "10002",
"key": "BETA",
"name": "Beta Platform",
"description": "Beta platform development",
"projectTypeKey": "software"
}
],
"count": 2
}
}
get_project_info
Get detailed information about a specific project.
Input Schema:
{
"type": "object",
"properties": {
"project_key": {
"type": "string",
"description": "Jira project key (e.g., PROJ)"
}
},
"required": ["project_key"]
}
Example Response:
{
"success": true,
"data": {
"id": "10001",
"key": "PROJ",
"name": "Project Alpha",
"description": "Main project for Alpha team development and maintenance",
"lead": {
"accountId": "abc123def456",
"displayName": "John Doe"
},
"projectTypeKey": "software",
"issueTypes": [
{ "id": "10001", "name": "Bug" },
{ "id": "10002", "name": "Task" },
{ "id": "10003", "name": "Story" },
{ "id": "10004", "name": "Epic" }
],
"components": [
{ "id": "10100", "name": "Backend" },
{ "id": "10101", "name": "Frontend" }
]
}
}
get_available_statuses
List all available workflow statuses for a project.
Input Schema:
{
"type": "object",
"properties": {
"project_key": {
"type": "string",
"description": "Jira project key"
}
},
"required": ["project_key"]
}
Example Response:
{
"success": true,
"data": {
"statuses": [
{
"id": "1",
"name": "To Do",
"category": "new",
"description": "Work that has not been started"
},
{
"id": "2",
"name": "In Progress",
"category": "indeterminate",
"description": "Work that is being actively worked on"
},
{
"id": "3",
"name": "In Review",
"category": "indeterminate",
"description": "Work pending review"
},
{
"id": "4",
"name": "Done",
"category": "done",
"description": "Completed work"
},
{
"id": "5",
"name": "Blocked",
"category": "indeterminate",
"description": "Work that is blocked"
}
]
}
}
get_assignable_users
List users who can be assigned to issues.
Input Schema:
{
"type": "object",
"properties": {
"project_key": {
"type": "string",
"description": "Jira project key"
},
"issue_key": {
"type": "string",
"description": "Specific issue key (optional)"
}
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"users": [
{
"accountId": "abc123def456",
"displayName": "John Doe",
"emailAddress": "john.doe@example.com",
"active": true,
"avatarUrls": {
"48x48": "https://avatar.example.com/john"
}
},
{
"accountId": "xyz789uvw012",
"displayName": "Jane Smith",
"emailAddress": "jane.smith@example.com",
"active": true
}
],
"count": 2
}
}
User Operations
get_users
List all Jira users in the instance.
Example Response:
{
"success": true,
"data": {
"users": [
{
"accountId": "abc123def456",
"displayName": "John Doe",
"emailAddress": "john.doe@example.com",
"active": true,
"accountType": "atlassian"
}
],
"count": 1
}
}
get_user_by_email
Look up a Jira user by email address.
Input Schema:
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "User email address"
}
},
"required": ["email"]
}
Example Response:
{
"success": true,
"data": {
"accountId": "abc123def456",
"displayName": "John Doe",
"emailAddress": "john.doe@example.com",
"active": true,
"accountType": "atlassian",
"avatarUrls": {
"48x48": "https://avatar.example.com/john"
}
}
}
get_tickets_by_user
Get all tickets assigned to a specific user.
Input Schema:
{
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "Jira account ID"
},
"assignee_id": {
"type": "string",
"description": "Alias for user_id"
},
"limit": {
"type": "integer"
}
},
"required": []
}
Ticket Operations
get_tickets
List Jira tickets with optional filters.
Input Schema:
{
"type": "object",
"properties": {
"project_key": {
"type": "string",
"description": "Optional - fetches from all accessible projects if not provided"
},
"project": {
"type": "string",
"description": "Alias for project_key"
},
"assignee_id": {
"type": "string",
"description": "Filter by assignee account ID"
},
"status": {
"type": "string",
"description": "Filter by status name"
},
"limit": {
"type": "integer"
}
},
"required": []
}
⚠️ Important: This is a Jira tool. Use project_key or project, NOT repo_id.
Example Request:
curl -X POST http://localhost:3007/mcp/jira/execute \
-H "Content-Type: application/json" \
-H "X-JWT-Token: <your-jwt-token>" \
-d '{
"tool": "get_tickets",
"arguments": {
"project_key": "PROJ",
"status": "In Progress",
"limit": 50
}
}'
Example Response:
{
"success": true,
"data": {
"tickets": [
{
"id": "10042",
"key": "PROJ-123",
"summary": "Implement user authentication",
"description": "Add OAuth2 authentication flow with refresh token support",
"status": {
"name": "In Progress",
"id": "2",
"category": {
"key": "indeterminate",
"name": "In Progress"
}
},
"priority": {
"name": "High",
"id": "2"
},
"issuetype": {
"name": "Story",
"id": "10003"
},
"assignee": {
"accountId": "abc123def456",
"displayName": "John Doe"
},
"reporter": {
"accountId": "xyz789",
"displayName": "Jane Smith"
},
"labels": ["authentication", "security"],
"created": "2024-01-10T09:00:00.000+0000",
"updated": "2024-01-20T14:30:00.000+0000",
"storyPoints": 5
}
],
"count": 1
}
}
get_ticket
Get details for a specific ticket.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": {
"type": "string",
"description": "Jira issue key (e.g., PROJ-123)"
}
},
"required": ["issue_key"]
}
Example Response:
{
"success": true,
"data": {
"id": "10042",
"key": "PROJ-123",
"summary": "Implement user authentication",
"description": "Add OAuth2 authentication flow with refresh token support.\n\n## Acceptance Criteria\n- User can login with OAuth2\n- Refresh tokens are securely stored",
"status": {
"name": "In Progress"
},
"priority": {
"name": "High"
},
"issuetype": {
"name": "Story"
},
"assignee": {
"accountId": "abc123def456",
"displayName": "John Doe"
},
"labels": ["authentication", "security"],
"components": [
{ "name": "Backend" }
],
"created": "2024-01-10T09:00:00.000+0000",
"updated": "2024-01-20T14:30:00.000+0000",
"storyPoints": 5,
"sprint": {
"id": 42,
"name": "Sprint 23",
"state": "active"
},
"subtasks": [
{
"key": "PROJ-124",
"summary": "Add OAuth2 provider",
"status": { "name": "Done" }
},
{
"key": "PROJ-125",
"summary": "Implement token refresh",
"status": { "name": "In Progress" }
}
]
}
}
create_ticket
Create a new Jira ticket.
Input Schema:
{
"type": "object",
"properties": {
"project_key": {
"type": "string",
"description": "Jira project key"
},
"summary": {
"type": "string",
"description": "Ticket title"
},
"issue_type": {
"type": "string",
"description": "Issue type: Task, Bug, Story, Epic"
},
"description": {
"type": "string",
"description": "Detailed description"
},
"priority": {
"type": "string",
"description": "Priority level: Highest, High, Medium, Low, Lowest"
},
"assignee_id": {
"type": "string",
"description": "Account ID of assignee"
},
"labels": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["project_key", "summary", "issue_type"]
}
Example Request:
curl -X POST http://localhost:3007/mcp/jira/execute \
-H "Content-Type: application/json" \
-H "X-JWT-Token: <your-jwt-token>" \
-d '{
"tool": "create_ticket",
"arguments": {
"project_key": "PROJ",
"summary": "Add rate limiting to API endpoints",
"issue_type": "Task",
"description": "Implement rate limiting to prevent API abuse.\n\n## Requirements\n- 100 requests per minute per user\n- Return 429 status when exceeded",
"priority": "High",
"labels": ["api", "security"]
}
}'
Example Response:
{
"success": true,
"data": {
"id": "10050",
"key": "PROJ-130",
"self": "https://your-instance.atlassian.net/rest/api/3/issue/10050"
}
}
update_ticket
Update an existing ticket.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" },
"summary": { "type": "string" },
"description": { "type": "string" },
"priority": { "type": "string" },
"assignee_id": { "type": "string" },
"labels": { "type": "array", "items": { "type": "string" } }
},
"required": ["issue_key"]
}
get_ticket_comments
List comments on a ticket.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" }
},
"required": ["issue_key"]
}
Example Response:
{
"success": true,
"data": {
"comments": [
{
"id": "10100",
"body": "Started working on the OAuth2 integration",
"author": {
"accountId": "abc123",
"displayName": "John Doe"
},
"created": "2024-01-15T10:30:00.000+0000",
"updated": "2024-01-15T10:30:00.000+0000"
},
{
"id": "10101",
"body": "Completed the token refresh implementation. Ready for review.",
"author": {
"accountId": "abc123",
"displayName": "John Doe"
},
"created": "2024-01-18T16:45:00.000+0000"
}
],
"count": 2
}
}
add_ticket_comment
Add a comment to a ticket.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" },
"comment": { "type": "string", "description": "Comment text" }
},
"required": ["issue_key", "comment"]
}
get_available_transitions
List available workflow transitions for a ticket.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" }
},
"required": ["issue_key"]
}
Example Response:
{
"success": true,
"data": {
"transitions": [
{
"id": "11",
"name": "Start Progress",
"to": {
"id": "2",
"name": "In Progress",
"category": "indeterminate"
}
},
{
"id": "21",
"name": "Done",
"to": {
"id": "4",
"name": "Done",
"category": "done"
}
},
{
"id": "31",
"name": "Block",
"to": {
"id": "5",
"name": "Blocked",
"category": "indeterminate"
}
}
]
}
}
transition_issue
Transition a ticket to a new status.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" },
"transition_name": {
"type": "string",
"description": "Name of the transition (use get_available_transitions to find valid names)"
},
"comment": {
"type": "string",
"description": "Optional comment to add with transition"
}
},
"required": ["issue_key", "transition_name"]
}
Example Request:
curl -X POST http://localhost:3007/mcp/jira/execute \
-H "Content-Type: application/json" \
-H "X-JWT-Token: <your-jwt-token>" \
-d '{
"tool": "transition_issue",
"arguments": {
"issue_key": "PROJ-123",
"transition_name": "Done",
"comment": "Completed implementation and all tests passing"
}
}'
assign_issue
Assign a ticket to a user.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" },
"assignee_id": {
"type": "string",
"description": "Account ID (use get_assignable_users to find)"
}
},
"required": ["issue_key", "assignee_id"]
}
get_issues_by_status
Get tickets filtered by status.
Input Schema:
{
"type": "object",
"properties": {
"project_key": { "type": "string", "description": "Optional" },
"status": { "type": "string", "description": "Status name" },
"limit": { "type": "integer" }
},
"required": ["status"]
}
get_issue_aging
Get ticket aging information.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" }
},
"required": ["issue_key"]
}
Example Response:
{
"success": true,
"data": {
"issue_key": "PROJ-123",
"created": "2024-01-10T09:00:00.000+0000",
"age_days": 15,
"current_status": "In Progress",
"time_in_status_hours": 48.5,
"status_history": [
{
"from": "To Do",
"to": "In Progress",
"when": "2024-01-12T10:00:00.000+0000",
"duration_hours": 49.0
}
]
}
}
add_issue_labels / remove_issue_labels
Add or remove labels from a ticket.
Input Schema:
{
"type": "object",
"properties": {
"issue_key": { "type": "string" },
"labels": { "type": "array", "items": { "type": "string" } }
},
"required": ["issue_key", "labels"]
}
Metrics Operations
get_developer_metrics
Get developer productivity metrics.
Input Schema:
{
"type": "object",
"properties": {
"project_key": {
"type": "string",
"description": "Optional - aggregates all projects if not provided"
},
"time_period_days": {
"type": "integer",
"description": "Time period (default: 30)"
},
"limit": { "type": "integer" }
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"developers": [
{
"accountId": "abc123def456",
"displayName": "John Doe",
"issues": {
"total": 25,
"created": 8,
"resolved": 15,
"in_progress": 2,
"blocked": 0
},
"by_type": {
"bugs": 5,
"stories": 12,
"tasks": 8
},
"story_points": {
"total": 45,
"completed": 38,
"average_per_issue": 3.5
},
"time_metrics": {
"avg_resolution_hours": 36.5,
"avg_cycle_time_hours": 48.2,
"time_logged_hours": 120
}
}
],
"period_days": 30,
"total_developers": 1
}
}
get_dora_metrics
Get DORA metrics for Jira projects.
Input Schema:
{
"type": "object",
"properties": {
"project_key": { "type": "string", "description": "Optional" },
"time_period_days": { "type": "integer" }
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"deployment_frequency": {
"value": 3.2,
"unit": "releases_per_week",
"category": "High"
},
"lead_time_for_changes": {
"value": 72.5,
"unit": "hours",
"category": "Medium",
"description": "Average time from issue creation to resolution"
},
"change_failure_rate": {
"value": 12.5,
"unit": "percent",
"category": "Medium",
"bugs_after_release": 5,
"total_releases": 40
},
"mean_time_to_recovery": {
"value": 8.2,
"unit": "hours",
"category": "High",
"incidents_count": 3
}
}
}
get_sprint_metrics
Get sprint velocity and completion metrics.
Input Schema:
{
"type": "object",
"properties": {
"project_key": { "type": "string", "description": "Optional" },
"current_only": {
"type": "boolean",
"description": "If true, returns only active sprint (default: true)"
}
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"sprint": {
"id": 42,
"name": "Sprint 23",
"state": "active",
"startDate": "2024-01-15T00:00:00.000+0000",
"endDate": "2024-01-29T00:00:00.000+0000",
"days_remaining": 5
},
"metrics": {
"total_issues": 18,
"completed": 12,
"remaining": 6,
"completion_rate_percent": 66.7,
"story_points": {
"committed": 45,
"completed": 30,
"remaining": 15,
"velocity": 30
},
"by_status": {
"Done": 12,
"In Progress": 4,
"To Do": 2
},
"burndown": {
"ideal_remaining": 8,
"actual_remaining": 6,
"status": "ahead"
}
}
}
}
get_throughput_metrics
Get aggregated throughput and delivery analytics.
Input Schema:
{
"type": "object",
"properties": {
"project_key": { "type": "string", "description": "Optional" },
"time_period_days": { "type": "integer" }
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"throughput": {
"issues_completed": 85,
"issues_per_day": 2.8,
"story_points_completed": 245
},
"cycle_time": {
"average_hours": 48.5,
"p50_hours": 36.0,
"p90_hours": 96.0
},
"lead_time": {
"average_hours": 72.3,
"p50_hours": 60.0,
"p90_hours": 144.0
},
"work_in_progress": {
"current_count": 15,
"avg_age_hours": 24.5
},
"flow_efficiency": {
"percent": 68.5,
"description": "Ratio of active work time to total time"
}
}
}
get_throughput_metrics_by_project
Get throughput metrics grouped by project.
get_project_productivity_metrics
Get productivity metrics for a specific project.
get_developer_ticket_metrics_all_projects
Get comprehensive developer ticket metrics.
Example Response:
{
"success": true,
"data": {
"developers": [
{
"accountId": "abc123",
"displayName": "John Doe",
"tickets": {
"created": 12,
"resolved": 18,
"current_workload": 5
},
"cycle_time_hours": 36.5,
"lead_time_hours": 72.0,
"velocity": {
"story_points_per_sprint": 25,
"issues_per_sprint": 8
},
"by_issue_type": {
"Bug": { "resolved": 6, "avg_resolution_hours": 24.0 },
"Story": { "resolved": 10, "avg_resolution_hours": 48.0 },
"Task": { "resolved": 2, "avg_resolution_hours": 12.0 }
}
}
],
"team_totals": {
"issues_resolved": 45,
"story_points_delivered": 120
}
}
}
get_executive_summary_all_projects
Get executive summary with health scores and risk indicators.
Input Schema:
{
"type": "object",
"properties": {
"time_period_days": {
"type": "integer",
"description": "Time period (default: 7 days)"
}
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"period": {
"start": "2024-01-13T00:00:00.000+0000",
"end": "2024-01-20T00:00:00.000+0000",
"days": 7
},
"health_score": {
"overall": 85,
"category": "Healthy",
"trend": "stable",
"factors": {
"delivery": 90,
"quality": 82,
"velocity": 83
}
},
"delivery": {
"issues_completed": 45,
"story_points_delivered": 120,
"completion_rate_percent": 78.5,
"avg_cycle_time_hours": 36.5
},
"quality": {
"bugs_created": 8,
"bugs_resolved": 12,
"bug_resolution_rate_percent": 150,
"escaped_defects": 1
},
"risks": [
{
"type": "blocked_issues",
"severity": "medium",
"count": 3,
"description": "3 issues blocked for more than 48 hours",
"issues": ["PROJ-45", "PROJ-67", "PROJ-89"]
},
{
"type": "overdue_issues",
"severity": "low",
"count": 2,
"description": "2 issues past due date"
}
],
"team_activity": {
"active_developers": 8,
"avg_issues_per_developer": 5.6,
"top_contributors": [
{ "name": "John Doe", "issues_completed": 12 },
{ "name": "Jane Smith", "issues_completed": 10 }
]
},
"projects": [
{
"key": "PROJ",
"name": "Project Alpha",
"issues_completed": 28,
"health_score": 88
},
{
"key": "BETA",
"name": "Beta Platform",
"issues_completed": 17,
"health_score": 82
}
]
}
}
get_my_jira_work
Get all open Jira work for a user.
Input Schema:
{
"type": "object",
"properties": {
"user_identifier": {
"type": "string",
"description": "Email, account_id, or username (defaults to authenticated user)"
}
},
"required": []
}
Example Response:
{
"success": true,
"data": {
"user": {
"accountId": "abc123",
"displayName": "John Doe",
"email": "john.doe@example.com"
},
"summary": {
"total_open": 8,
"in_progress": 3,
"blocked": 1,
"overdue": 0,
"high_priority": 2
},
"by_status": {
"In Progress": [
{
"key": "PROJ-123",
"summary": "Implement OAuth2",
"priority": "High",
"project": "Project Alpha"
}
],
"Blocked": [
{
"key": "PROJ-125",
"summary": "Database migration",
"priority": "Medium",
"blocked_reason": "Waiting for DBA approval"
}
],
"To Do": [
{
"key": "PROJ-130",
"summary": "Add rate limiting",
"priority": "High"
}
]
},
"by_project": {
"PROJ": {
"project_name": "Project Alpha",
"count": 5
},
"BETA": {
"project_name": "Beta Platform",
"count": 3
}
}
}
}
Error Handling
Common Errors
Project Not Found:
{
"success": false,
"error": "Project 'INVALID' not found or not accessible"
}
Issue Not Found:
{
"success": false,
"error": "Issue 'PROJ-99999' not found"
}
Invalid Transition:
{
"success": false,
"error": "Transition 'Invalid Status' not available for issue PROJ-123"
}
Authentication Error:
{
"success": false,
"error": "Invalid Jira API token or insufficient permissions"
}
Best Practices
- Use Parallel Fetching: Omit
project_keyto fetch from all projects in parallel - Check Transitions First: Call
get_available_transitionsbeforetransition_issue - User Lookup: Use
get_user_by_emailwhen you have emails from other systems - Monitor Blocked Issues: Use
get_issues_by_statuswith "Blocked" regularly - Executive Reports: Use
get_executive_summary_all_projectsfor stakeholder updates