jira-mcp-server

angelescostarelliExtendeal/jira-mcp-server

3.2

If you are the rightful owner of jira-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that integrates with Jira API for issue retrieval and search.

Tools
5
Resources
0
Prompts
0

Jira MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Jira API, allowing you to retrieve and search Jira issues through various tools.

Features

  • Get specific Jira issues by issue key
  • Search issues using JQL (Jira Query Language)
  • Get issues by epic with optional filtering
  • Get project issues with status and assignee filters
  • Get user-assigned issues with status filtering
  • Rich issue formatting with all relevant fields
  • Error handling with detailed error messages

Prerequisites

  • Node.js 18+
  • Yarn or npm
  • Jira Cloud instance with API access
  • Jira API token

Installation

  1. Clone or download this repository

  2. Install dependencies:

    yarn install
# or
npm install

  3. Copy the environment template:

    cp .env.example .env

  4. Configure your Jira credentials in .env:

    JIRA_DOMAIN=https://yourcompany.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token-here
JIRA_PROJECT_KEY=PROJ
JIRA_ISSUE_TYPE=Task

Getting Your Jira API Token

  1. Go to Atlassian Account Settings
  2. Click "Create API token"
  3. Give it a label (e.g., "MCP Server")
  4. Copy the generated token and paste it in your .env file

Building and Running

Development

yarn dev
# or
npm run dev

Production

yarn build
yarn start
# or
npm run build
npm start

MCP Configuration

To use this server with an MCP client (like Claude Desktop), add it to your MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/jira-mcp-server"
    }
  }
}

Replace /path/to/jira-mcp-server with the actual path to your server directory.

For Claude Desktop, this configuration goes in:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json

Available Tools

1. get_jira_issue

Get a specific Jira issue by its key.

Parameters:

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

Example:

{
  "name": "get_jira_issue",
  "arguments": {
    "issueKey": "PROJ-123"
  }
}

2. search_jira_issues

Search Jira issues using JQL (Jira Query Language).

Parameters:

  • jql (string, required): JQL query string
  • maxResults (number, optional): Maximum results to return (default: 50)
  • fields (string, optional): Comma-separated fields to include

Example:

{
  "name": "search_jira_issues",
  "arguments": {
    "jql": "project = PROJ AND status = 'In Progress'",
    "maxResults": 25
  }
}

3. get_issues_by_epic

Get all issues belonging to a specific epic with optional filters.

Parameters:

  • epicKey (string, required): The epic issue key
  • priority (string, optional): Filter by priority
  • assignee (string, optional): Filter by assignee
  • labels (array, optional): Filter by labels

Example:

{
  "name": "get_issues_by_epic",
  "arguments": {
    "epicKey": "PROJ-100",
    "priority": "High",
    "assignee": "john.doe@company.com"
  }
}

4. get_project_issues

Get issues from a specific project.

Parameters:

  • projectKey (string, required): The project key
  • status (string, optional): Filter by status
  • assignee (string, optional): Filter by assignee
  • maxResults (number, optional): Maximum results (default: 50)

Example:

{
  "name": "get_project_issues",
  "arguments": {
    "projectKey": "PROJ",
    "status": "To Do",
    "maxResults": 100
  }
}

5. get_user_assigned_issues

Get issues assigned to a specific user.

Parameters:

  • assignee (string, required): User email, displayName, or accountId
  • status (string, optional): Filter by status
  • maxResults (number, optional): Maximum results (default: 50)

Example:

{
  "name": "get_user_assigned_issues",
  "arguments": {
    "assignee": "john.doe@company.com",
    "status": "In Progress"
  }
}

Response Format

All tools return issue data in the following format:

{
  "key": "PROJ-123",
  "summary": "Issue summary",
  "description": "Issue description (plain text)",
  "status": "In Progress",
  "assignee": "John Doe",
  "priority": "High",
  "issueType": "Story",
  "labels": ["frontend", "urgent"],
  "created": "1/15/2024",
  "updated": "1/20/2024",
  "url": "https://yourcompany.atlassian.net/browse/PROJ-123"
}

JQL Examples

Here are some useful JQL queries you can use with the search_jira_issues tool:

  • Get all open issues: status != Done
  • Get high priority bugs: issuetype = Bug AND priority = High
  • Get issues updated in the last week: updated >= -1w
  • Get issues assigned to you: assignee = currentUser()
  • Get issues in specific sprint: sprint = "Sprint 1"
  • Complex query: project = PROJ AND status IN ("To Do", "In Progress") AND assignee != EMPTY ORDER BY priority DESC

Error Handling

The server provides detailed error messages for common issues:

  • Invalid issue keys
  • Authentication failures
  • Invalid JQL syntax
  • Network connectivity issues
  • Permission errors

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

ISC License

Support

For issues and questions:

  1. Check the Jira API documentation
  2. Verify your API token and permissions
  3. Test your JQL queries in Jira's issue search
  4. Check the server logs for detailed error messages