eh24905-wiz/jira-mcp

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:

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:

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:

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 file for details.