aderik/mcp-server-jira

JIRA MCP Server

This is a Model Context Protocol (MCP) server that provides tools for interacting with JIRA. It allows you to fetch tickets from active sprints, search issues, manage users, and get detailed ticket information through the MCP interface.

⚠️ Updated for 2025: This fork includes critical fixes for Atlassian's API deprecations that caused 410 errors in the original version. All deprecated endpoints have been replaced with their modern equivalents.

Features

The server provides the following tools:

Issue Management

1. search-issues: Search for issues using JQL or filters

   • Optional parameter: jql (string) - Custom JQL query
   • Optional parameter: projectKey (string) - Filter by project
   • Optional parameter: issueType (string) - Filter by issue type (e.g., 'Bug', 'Task', 'Story')
   • Optional parameter: statusCategory (string) - Filter by status ('To Do', 'In Progress', 'Done')
   • Optional parameter: maxResults (number) - Max results to return (default: 20, max: 100)
   • Optional parameter: startAt (number) - Pagination offset

2. list-sprint-tickets: Gets all tickets in the active sprint for a given project

   • Required parameter: projectKey (string)

3. get-ticket-details: Gets detailed information about a specific ticket

   • Required parameter: issueKey (string)

4. add-comment: Adds a comment to a specific ticket

   • Required parameter: issueKey (string)
   • Required parameter: comment (string)

5. update-description: Updates the description of a specific ticket

   • Required parameter: issueKey (string)
   • Required parameter: description (string)

6. list-child-issues: Gets all child issues of a parent ticket

   • Required parameter: parentKey (string)

7. create-sub-ticket: Creates a sub-ticket (child issue) for a parent ticket

   • Required parameter: parentKey (string)
   • Required parameter: summary (string)
   • Optional parameter: description (string)
   • Optional parameter: issueType (string) - The name of the sub-task issue type (e.g., 'Sub-task')

8. create-ticket: Create a new ticket with custom fields

   • Required parameter: projectKey (string)
   • Required parameter: summary (string)
   • Optional parameter: description (string)
   • Optional parameter: issueType (string)
   • Optional parameter: parentKey (string) - Creates a sub-task if provided
   • Optional parameter: fields (object) - Additional custom fields

9. update-issues: Batch update fields on multiple tickets

   • Required parameter: issueKeys (array of strings)
   • Required parameter: fields (object) - Fields to update

10. add-labels: Add labels to multiple issues

    • Required parameter: issueKeys (array of strings)
    • Required parameter: labels (array of strings)

11. link-issues: Link multiple tickets using 'relates to' relationship

    • Required parameter: inwardIssueKeys (array of strings)
    • Required parameter: outwardIssueKeys (array of strings)

12. transition-issues: Transition multiple issues to a new status

    • Required parameter: issueKeys (array of strings)
    • Required parameter: transitionId (string)

13. list-issue-transitions: List available transitions for an issue

    • Required parameter: issueKey (string)

14. assign-issue: Assign issues to a user

    • Required parameter: issueKeys (array of strings)
    • Required parameter: assigneeDisplayName (string)

User & Field Management

15. list-users: List all users in Jira

    • Optional parameter: query (string) - Search string to filter users
    • Optional parameter: maxResults (number) - Max results (default: 50, max: 1000)

16. list-issue-fields: List all available issue fields including custom fields

    • Optional parameter: includeCustomOnly (boolean) - Only show custom fields

17. list-jira-filters: List all Jira filters

Setup

1. Install dependencies:

   npm install
   

2. Build the TypeScript code:

This step is only needed for Cline on Windows, which currently has an issue executing npx

npm run build

3. Configure the MCP settings in your Claude app settings file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json on Windows):

Settings for Claude:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Settings for Cline:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Configuration

Option 1: Local Development with .env file

For local development and testing, you can use a .env file:

1. Copy the example file:

   cp .env.example .env
   

2. Edit .env and add your credentials:

   JIRA_HOST=https://your-domain.atlassian.net
   JIRA_EMAIL=your-email@example.com
   JIRA_API_TOKEN=your-api-token
   

3. Run the server:

   npm start
   

Option 2: MCP Configuration

You'll need to set up the following environment variables in your MCP settings:

1. JIRA_HOST: Your Atlassian domain URL (e.g., https://your-company.atlassian.net)
2. JIRA_EMAIL: Your JIRA account email
3. JIRA_API_TOKEN: Your JIRA API token
   • You can generate an API token from your Atlassian Account Settings

Usage

Once configured, you can use the tools through the MCP interface in Claude:

List Sprint Tickets

To get all tickets in the active sprint for a project:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

Get Ticket Details

To get detailed information about a specific ticket:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

Development

The server is written in TypeScript and uses:

• @modelcontextprotocol/sdk for MCP server implementation
• jira.js for JIRA API integration

Recommended scripts:

• Build once: npm run build
• Build and watch: npm run build:watch
• Type-check only: npm run typecheck
• Dev run with watch: npm run start:dev
• Run compiled server: npm start
• Format check: npm run fmt:check
• Format write: npm run fmt

Typical workflow:

1. Make changes to
2. Run npm run start:dev during development, or npm run build then npm start for compiled run
3. Restart your MCP client if needed to pick up changes

Recent Updates (2025)

Critical Fixes for Atlassian API Deprecations

This fork includes fixes for the following deprecated endpoints that were causing 410 Gone errors:

1. /rest/api/3/users/search → Migrated to /rest/api/3/user/search

   • Affects: list-users tool
   • Fixed: Updated to use userSearch.findUsers() with proper pagination

2. /rest/api/3/search → Migrated to /rest/api/3/search/jql

   • Affects: search-issues and list-sprint-tickets tools
   • Fixed: Updated to use searchForIssuesUsingJqlEnhancedSearch() with token-based pagination
   • Note: The new API requires bounded JQL queries (unbounded queries now default to last 30 days)

Other Improvements

• Updated jira.js dependency from 4.1.3 to 5.2.2
• Added .env file support for local development with dotenv
• Enhanced error messages with full response details for easier debugging
• Added test script (test-local.sh) for local development
• Improved pagination handling with new token-based system

Error Handling

The server includes error handling for:

• Invalid JIRA credentials
• Missing active sprints
• Invalid project keys or issue keys
• Network errors
• Deprecated API endpoints (with automatic migration to new endpoints)

Error messages will be returned in the tool response with detailed information.

Migration from Original Version

If you're migrating from the original boukeversteegh/mcp-server-jira:

1. Update your local repository:

   git pull
   npm install
   npm run build
   

2. Restart your MCP client (Cursor/Claude)

3. All tools should now work without 410 errors

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0 License

Credits

• Original version by boukeversteegh
• 2025 updates and fixes by aderik