suffle/jira-mcp-server

@suffle/jira-mcp-server

MCP (Model Context Protocol) server for enriching prompts with Jira ticket data. Converts Atlassian Document Format (ADF) to Markdown and provides a powerful templating system.

Features

• 🎫 Fetch comprehensive Jira ticket data via REST API
• 📝 Convert ADF (Atlassian Document Format) rich text to Markdown
• 🎨 Powerful templating with conditionals and loops
• 🔧 Easy configuration via environment variables
• 📦 Use as npm package with npx
• 💪 TypeScript with full type safety

Installation

As a global package

npm install -g @suffle/jira-mcp-server
# or
pnpm add -g @suffle/jira-mcp-server

With npx (no installation)

npx @suffle/jira-mcp-server

Quick Start

1. Get Jira API Credentials

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Save your API key

2. Configure Environment Variables

Set these environment variables:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_USERNAME="your-email@example.com"
export JIRA_API_KEY="your-api-key-here"

Optional:

export JIRA_PROMPT_PATH="/path/to/custom-template.txt"

3. Configure MCP Client

For Claude Desktop

Edit your MCP configuration file:

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

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here"
      }
    }
  }
}

For VS Code MCP

Create .vscode/mcp.json:

{
  "servers": {
    "jira": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here",
        "JIRA_PROMPT_PATH": "${workspaceFolder}/prompts/my-template.txt"
      }
    }
  }
}

4. Use the Prompt

In your MCP client (Claude Desktop, VS Code, etc.):

/jira_ticket PROJ-123

This fetches the ticket data and inserts an enriched prompt into your message input for review and editing before sending.## Template System

Template Syntax

Basic Placeholders:

{{ ticket.key }}
{{ ticket.summary }}
{{ ticket.description }}
{{ ticket.status }}
{{ ticket.priority }}
{{ ticket.assignee }}
{{ ticket.reporter }}
{{ ticket.issueType }}
{{ ticket.created }}
{{ ticket.updated }}
{{ ticket.url }}
{{ today }}
{{ now }}

Conditional Blocks:

{{#if ticket.assignee}}
Assignee: {{ ticket.assignee }}
{{/if}}

Loops (for arrays):

{{#if ticket.labels}}
Labels:
{{#each ticket.labels}}
- {{ this }}
{{/each}}
{{/if}}

Available Data Fields

Simple Fields:

• ticket.key - The Jira ticket key (e.g., PROJ-123)
• ticket.id - Internal ticket ID
• ticket.summary - Ticket summary/title
• ticket.description - Ticket description
• ticket.status - Current status
• ticket.statusCategory - Status category (To Do, In Progress, Done)
• ticket.priority - Priority level
• ticket.issueType - Type of issue (Bug, Story, Task, etc.)
• ticket.assignee - Assigned person name
• ticket.assigneeEmail - Assignee's email
• ticket.reporter - Reporter name
• ticket.reporterEmail - Reporter's email
• ticket.created - Creation date (formatted)
• ticket.updated - Last update date (formatted)
• ticket.url - Direct URL to ticket

Array Fields (use with #each):

• ticket.labels - Array of labels
• ticket.components - Array of components
• ticket.fixVersions - Array of fix versions
• ticket.affectedVersions - Array of affected versions

Date Fields:

• today - Current date (formatted)
• now - Current date and time (formatted)

Example Template

# {{ ticket.key }}: {{ ticket.summary }}

**Type:** {{ ticket.issueType }}
**Status:** {{ ticket.status }}
**Priority:** {{ ticket.priority }}

## Description
{{ ticket.description }}

## Details
- **Reporter:** {{ ticket.reporter }}
{{#if ticket.assignee}}
- **Assignee:** {{ ticket.assignee }}
{{/if}}
- **Created:** {{ ticket.created }}
- **Updated:** {{ ticket.updated }}

{{#if ticket.labels}}
## Labels
{{#each ticket.labels}}
- {{ this }}
{{/each}}
{{/if}}

{{#if ticket.components}}
## Components
{{#each ticket.components}}
- {{ this }}
{{/each}}
{{/if}}

[View in Jira]({{ ticket.url }})

Available Data Fields

Multiple Configurations

You can run multiple server instances with different template files:

{
  "mcpServers": {
    "jira-default": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here"
      }
    },
    "jira-detailed": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here",
        "JIRA_PROMPT_PATH": "/Users/you/templates/detailed.txt"
      }
    }
  }
}

Development

Local Development

git clone https://github.com/suffle/jira-mcp-server.git
cd jira-mcp-server
pnpm install
pnpm build

Running Tests

pnpm test
pnpm test:coverage

Publishing

The package is automatically published to npm when you push a git tag:

git tag v1.0.1
git push origin v1.0.1

Required GitHub Secrets:

• NPM_TOKEN - Your npm authentication token

To get an npm token:

1. Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
2. Click "Generate New Token" → "Classic Token"
3. Select "Automation" type
4. Copy the token and add it to your GitHub repository secrets

License

MIT

Author

suffle

Repository

https://github.com/suffle/jira-mcp-server