mcp-jira-cloud-v2

Jira Requester MCP Server

This is a Message Communication Protocol (MCP) server designed to interact with the Jira API (v2 client) to fetch ticket information.

Prerequisites

• Node.js (Recommended version: >= 20.x.x)
• npm (comes with Node.js)
• Jira Cloud instance
• Jira API Token

Installation

1. Clone the repository:

   git clone https://github.com/scho-to/mcp-jira-cloud-v2.git
   cd mcp-jira-cloud-v2
   

2. Install dependencies:

   npm install
   

Configuration

This server requires environment variables for Jira authentication and connection:

• JIRA_URL: The base URL of your Jira instance (e.g., https://your-domain.atlassian.net).
• JIRA_USER_EMAIL: The email address associated with your Jira account.
• JIRA_API_TOKEN: Your Jira API token. You can generate one from your Atlassian account settings.

Create a .env file in the project root and add these variables (or set them in your environment):

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

Important: If you use a .env file, ensure it's added to your .gitignore to avoid committing sensitive credentials.

Usage

1. Build the project:

   npm run build
   

2. Start the server (after building):

   npm start
   

   Alternatively, to run the server in development mode with hot-reloading (compiles and runs):

   npm run dev
   

3. Interact via MCP: Once the server is running (either via npm start or npm run dev), it will listen for MCP requests.

Testing

You can test the Jira client functionality directly using the simpleTest.ts script. This script requires Jira credentials to be set as environment variables.

1. Run the test script: Provide a Jira ticket ID as an argument.

   npm test -- <JIRA_TICKET_ID>
   

   (The -- is important for passing arguments to the script via npm)

Building

The project is built using the TypeScript compiler (tsc). This compiles the TypeScript source files (.ts) from src into JavaScript files (.js) in the build directory.

To build the project:

npm run build

MCP Server Configuration

To set up this server within an MCP environment, add the following configuration to your MCP config file:

{
  "mcpServers": {
    "jira-requester": {
      "command": "node",
      "env": {
        "JIRA_URL": "https://your-instance.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      },
      "args": ["/path/to/mcp-jira-cloud-v2/build/index.js"]
    }
  }
}

Note: Replace placeholders like https://your-instance.atlassian.net, your-email@example.com, your-api-token, and /path/to/mcp-jira-cloud-v2/build/index.js with your actual Jira instance URL, credentials, and the correct path to the built index.js file.

Security Warning: Avoid committing sensitive information like API tokens directly into your configuration files. Consider using environment variables or a secrets management system.

Available Tools

get_jira_ticket

Fetches details for a specific Jira ticket.

Parameters:

• ticket_id (string, required): The ID of the Jira ticket (e.g., PROJ-123).
• fields (array of strings, optional): Specify which fields to include in the response. If omitted, default fields might be returned.
• expand (array of strings, optional): Specify Jira fields to expand (e.g., changelog, renderedFields).

Example MCP Request:

{
  "tool_name": "get_jira_ticket",
  "parameters": {
    "ticket_id": "PROJ-123",
    "fields": ["summary", "status", "assignee"],
    "expand": ["renderedFields"]
  }
}