Jira MCP Server

A Model Context Protocol (MCP) server for Jira integration, enabling AI assistants to interact with Jira issues, comments, and custom fields through a standardized interface.

Features

This MCP server provides the following tools:

Tool	Description
get_my_issues	Get all issues currently assigned to you
get_issue_details	Get full details of a specific Jira issue
add_comment	Add a comment to a specified Jira issue
get_my_work_summary	Get a summary of issues you've worked on within a date range
get_team_activity	Get recent issue updates from configured team members
get_project_components	Get all available components for a Jira project
update_issue_field	Update supported custom fields on a Jira issue
update_progress	Update the Progress Update field with template-aware behavior
create_issue	Create a new issue in Jira with support for custom fields
get_sprint_tasks	Retrieve sprint tasks for the current week or next week

Prerequisites

• Node.js: v18.0.0 or higher
• npm: v8.0.0 or higher
• Jira Cloud Account: With API access enabled
• Jira API Token: Generated from your Atlassian account

Installation

1. Clone the repository:

   git clone <repository-url>
   cd jira-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Environment Variables

The server requires the following environment variables:

Variable	Description	Example
JIRA_BASE_URL	Your Jira instance base URL	https://your-org.atlassian.net
JIRA_USER_EMAIL	Your Jira account email	user@example.com
JIRA_API_TOKEN	Jira API token (Generate here)	ATATT3xFfGF0...
JIRA_CURRENT_USER	(Optional) Override current user for queries	currentuser()
JIRA_TEAM_MEMBERS	(Optional) Comma-separated list of team member emails	user1@example.com,user2@example.com

Usage

Starting the Server

# Production
npm start

# Development (with hot reload)
npm run dev

MCP Client Configuration

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_TEAM_MEMBERS": "teammate1@example.com,teammate2@example.com"
      }
    }
  }
}

Supported Custom Fields

The following custom fields can be updated using update_issue_field:

Field Name	Field ID	Type	Description
Decision Needed	customfield_15111	Rich text (ADF)	Flag if a decision is required
Progress Update	customfield_15112	Rich text (ADF)	Weekly progress status
Decision Maker(s)	customfield_15113	User picker	Person responsible for decisions
Risks/Blockers	customfield_15115	Rich text (ADF)	Current risks or blockers
Completion Percentage	customfield_15116	Number	Progress percentage (0-100)
Health Status	customfield_15117	Select	Project health (On Track, At Risk, etc.)

API Reference

get_my_issues

Returns all unresolved issues assigned to the current user.

Parameters: None

Returns: Array of issues with key, summary, status, priority, updated

---

get_issue_details

Get full details of a specific issue.

Parameters:

• issueKey (string, required): The issue key (e.g., "PROJ-123")

Returns: Issue object with key, summary, description, status, priority, assignee, reporter, created, updated, comments

---

add_comment

Add a comment to an issue.

Parameters:

• issueKey (string, required): The issue key
• commentBody (string, required): The comment text

Returns: { success: boolean, commentId: string, created: string }

---

get_my_work_summary

Get issues you've worked on within a date range.

Parameters:

• startDate (string, required): Start date in YYYY-MM-DD format
• endDate (string, required): End date in YYYY-MM-DD format

Returns: Array of issues with activity type

---

get_team_activity

Get recent updates from team members.

Parameters:

• timeframeDays (number, optional): Days to look back (default: 7)

Returns: Array of activity items with issueKey, teamMember, activityType, timestamp, summary

---

update_issue_field

Update a custom field on an issue.

Parameters:

• issueKey (string, required): The issue key
• fieldNameOrId (string, required): Field name or ID
• value (string | number | object, required): Value to set

Returns: { success: boolean, fieldId: string, fieldName: string }

---

update_progress

Update the Progress Update field with template awareness.

Parameters:

• issueKey (string, required): The issue key
• refreshDate (boolean, optional): Update date only, preserve content
• weeklyUpdate (string, optional): Weekly update text
• delivered (string, optional): What was delivered
• whatsNext (string, optional): Upcoming work

Returns: { success: boolean, updatedSections: string[], parsedExisting: object }

The Progress Update field uses a structured template:

• ℹ️ Update for week of [date]: - Weekly status
• ✅ What we've delivered so far: - Accomplishments
• ❓ What's next: - Upcoming work

---

get_project_components

Get all available components for a Jira project.

Parameters:

• projectKey (string, required): The project key (e.g., "TSSE")

Returns: { components: [{ id: string, name: string, description?: string }] }

---

create_issue

Create a new issue in Jira with support for standard and custom fields.

Parameters:

• projectKey (string, required): The project key (e.g., "TSSE")
• issueType (string, required): The issue type (e.g., "Epic", "Story", "Task", "Bug")
• summary (string, required): Issue summary/title
• description (string, optional): Issue description (plain text)
• assignee (string, optional): Assignee accountId or "currentuser()" for current user
• priority (string, optional): Priority name (e.g., "High", "Medium", "Low")
• labels (string[], optional): Array of labels to apply
• duedate (string, optional): Due date in YYYY-MM-DD format
• components (string[], optional): Array of component names
• healthStatus (string, optional): Health Status value (e.g., "On Track", "At Risk", "Off Track")
• completionPercentage (number, optional): Completion percentage (0-100)
• decisionNeeded (string, optional): Decision Needed field content
• risksBlockers (string, optional): Risks/Blockers field content
• progressUpdate (object, optional): Progress Update with weeklyUpdate, delivered, whatsNext
• customFields (object, optional): Additional custom fields as key-value pairs

Returns: { success: boolean, key: string, id: string, self: string }

---

get_sprint_tasks

Retrieve sprint tasks for the current week or next week. Sprint tasks are tagged with labels in the format MonDD-DD (e.g., Dec15-19 for December 15-19).

Parameters:

• week (enum, required): Which week to retrieve - "this_week" or "next_week"
• scope (enum, required): Scope of tasks - "my_tasks" for current user only, "team_tasks" for all team tasks

Returns:

{
  "sprintLabel": "Dec15-19",
  "weekRange": { "monday": "2024-12-15", "friday": "2024-12-19" },
  "tasks": [{ "key": "PROJ-123", "summary": "...", "status": "...", "priority": "...", "assignee": "...", "updated": "..." }]
}

Development

Building

npm run build

Project Structure

jira-mcp/
├── src/
│   ├── index.ts        # MCP server entry point and tool definitions
│   └── jira-client.ts  # Jira API client wrapper
├── dist/               # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.