📊 Jira Stories MCP Server# 📊 Jira Stories MCP Server

**An intelligent bridge between your Jira stories and AI assistants****Model Context Protocol (MCP) server for querying and interacting with Jira Stories**

What is This Project?Provides real-time access to Jira stories with:

This is a Model Context Protocol (MCP) server that connects your Jira project stories directly to AI assistants like Claude. It transforms your Jira workspace into an intelligent, queryable knowledge base that AI can understand and interact with naturally.- ✅ View all stories in your Jira project

• ✅ Query specific stories by key

Why Does This Matter?- ✅ Filter by status (Open, In Progress, Done, etc.)

• ✅ Search stories by keywords

The Problem- ✅ Ask questions about stories using AI

• Teams struggle to get quick insights from their Jira stories- ✅ Access story details including description, comments, and metadata

• Finding relevant information across multiple stories is time-consuming

• Understanding project status requires manual filtering and aggregation## 🎯 Features

• Context switching between Jira and development work disrupts flow

• Resources: Access individual stories or collections via URI templates

The Solution- Prompts: Interactive prompts for viewing and querying stories

This MCP server acts as an intelligent intermediary that:- Tools: Programmatic access to story data for AI assistants

• Brings Jira to your AI assistant - No need to switch contexts or open Jira in a browser- Real-time: Fetches latest story data from Jira API

• Enables natural language queries - Ask questions in plain English instead of using JQL- Rich Context: Includes description, status, assignee, comments, and more

• Provides instant insights - Get summaries, status updates, and story details immediately

• Maintains real-time sync - Always shows current story data from your Jira instance## Installation & Setup

How Does It Help?### Prerequisites

For Developers- Node.js 18+ installed

• Quick Story Lookup: Ask "What's story TBC-123 about?" instead of searching Jira- Jira account with API access

• Context Without Switching: Get story details while coding without leaving your IDE- Jira API token (generate at https://id.atlassian.com/manage-profile/security/api-tokens)

• Smart Filtering: Find relevant stories by asking natural questions

• Status Awareness: Know what's in progress, blocked, or ready without manual checking### Global Installation

For Project Managers```bash

• Instant Status Reports: Ask "What stories are in progress?" for immediate updates# From the server project directory

• Priority Overview: Get high-priority story summaries on demandnpm install

• Team Insights: Understand who's working on what with simple queriesnpm run build

• Trend Analysis: Ask about patterns across multiple storiesnpm link

For Teams# Verify installation

• Shared Knowledge Base: Everyone can access story information through conversational AIwhich jira-stories # Should show the global path

• Reduced Meetings: Get answers to common status questions instantlyjira-stories # Should start the server (Ctrl+C to exit)

• Better Documentation: AI can summarize story details and comments```

• Improved Collaboration: Discuss stories with AI assistance for clarity

Environment Configuration

Key Capabilities

1. Copy the example environment file:

1. View All Your Stories

See a complete list of stories in your project, with status, assignees, and priorities at a glance.```bash

cp .env.example .env

2. Deep Dive Into Specifics```

Get full details of any story including description, comments, labels, history, and metadata.

2. Edit .env with your Jira credentials:

3. Smart Filtering

Filter stories by status (Open, In Progress, Done, etc.) without writing complex queries.```bash

JIRA_BASE_URL=https://your-domain.atlassian.net

4. Keyword SearchJIRA_EMAIL=your-email@company.com

Find stories by searching through titles and descriptions using natural language.JIRA_API_TOKEN=your_jira_api_token_here

JIRA_PROJECT_KEY=YOUR_PROJECT_KEY # e.g., "TBC", "PROJ", etc.

5. Contextual Questions

Ask AI questions about your stories and get intelligent answers based on actual data:USE_HTTP=true

• "What are the blockers in our current sprint?"PORT=8080

• "Summarize all high-priority authentication stories"```

• "Which stories are assigned but not started?"

• "What did the team discuss in TBC-456?"## Usage

6. Real-Time Data### 1. Start the MCP Server

Always works with the latest information from your Jira instance - no stale data.

Stdio Mode (for VS Code integration):

Use Cases

**Daily Standup Preparation**  jira-stories

"Show me all stories I'm assigned to and their current status"```



**Sprint Planning**  **HTTP Mode** (for testing and debugging):

"What high-priority stories are unassigned?"

```bash

**Code Review Context**  USE_HTTP=true jira-stories

"Tell me about the story related to this pull request"# Server starts at http://localhost:8080/mcp

Status Updates

"What stories moved to 'Done' this week?"### 2. Available Resources

Blocker Identification Access stories via URI templates:

"Are there any stories marked as blocked?"

• story://{key} - Get a specific story (e.g., story://TBC-123)

Knowledge Transfer - stories://all - Get all stories in the project

"Explain the context and decisions made in story XYZ"- stories://status/{status} - Get stories by status (e.g., stories://status/In Progress)

What You Can Ask### 3. Available Prompts

Once configured with your AI assistant, you can have natural conversations:Use these prompts in your MCP client:

• "Show me all Jira stories"- view-all-stories - View all Jira stories

• "What stories are in progress?"- view-story (storyKey) - View details of a specific story

• "Tell me about story TBC-123"- view-stories-by-status (status) - View stories filtered by status

• "Search for stories about authentication"- ask-about-stories (question) - Ask AI questions about your stories

• "What open stories are assigned to John?"

• "Summarize all high priority stories"### 4. Available Tools

• "Which stories have been updated today?"

• "What are the oldest open stories?"Programmatic access for AI assistants:

Technical Overview- get-all-stories - Get list of all stories

• get-story (storyKey) - Get details of a specific story

The server connects to your Jira instance via the Jira REST API and exposes story data through the Model Context Protocol (MCP). This allows AI assistants to access, query, and reason about your Jira stories as if they were part of the AI's knowledge base.- get-stories-by-status (status) - Get stories by status

• search-stories (keyword) - Search stories by keyword

No code changes needed - Just configure your Jira credentials and the server handles everything else.- get-open-stories - Get all open/in-progress stories

• refresh-stories - Refresh stories from Jira server

Requirements- ping (message) - Test tool connectivity

The server requires:## Integration with Claude Desktop

• A Jira account with API access

• An API token from your Jira instanceAdd this configuration to your Claude Desktop config:

• Your Jira project key (e.g., "TBC", "PROJ")

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Once configured, it runs locally and integrates with AI assistants like Claude Desktop, enabling you to have natural conversations about your Jira stories.Windows: %APPDATA%/Claude/claude_desktop_config.json

Privacy & Security```json

{

• Runs locally on your machine "mcpServers": {

• Connects directly to your Jira instance "jira-stories": {

• No third-party data storage "command": "jira-stories",

• Your credentials stay in your environment "env": {

• Full control over what data is accessed "JIRA_BASE_URL": "https://your-domain.atlassian.net",

    "JIRA_EMAIL": "your-email@company.com",
  

Who Should Use This? "JIRA_API_TOKEN": "your_api_token_here",

    "JIRA_PROJECT_KEY": "YOUR_PROJECT_KEY"

• Development Teams using Jira for story tracking }

• Project Managers needing quick insights without Jira navigation }

• Product Owners wanting to query backlog and sprint data naturally }

• Scrum Masters preparing for standups and retrospectives}

• Anyone who wants to interact with Jira stories through AI conversations```

The VisionAfter adding the configuration, restart Claude Desktop.

Transform Jira from a ticket management system into an intelligent, conversational knowledge base where you can get answers, insights, and context through natural dialogue with AI - making project information more accessible and actionable for everyone on the team.## Example Queries

---Once integrated, you can ask Claude:

This project bridges the gap between structured project management and conversational AI, making your Jira stories truly intelligent and accessible.- "Show me all Jira stories"

• "What stories are in progress?"
• "Tell me about story TBC-123"
• "Search for stories about authentication"
• "What open stories are assigned to John?"
• "Summarize all high priority stories"

Development

Build

npm run build

Run in Development Mode

# Stdio mode
npm run dev

# HTTP mode
npm run dev:http

Inspect with MCP Inspector

npm run inspect

API Reference

Story Object Structure

{
  key: string;           // e.g., "TBC-123"
  title: string;         // Story title
  description: string;   // Full description
  status: string;        // e.g., "In Progress", "Done"
  assignee?: string;     // Assigned user
  reporter?: string;     // Reporter user
  created: string;       // ISO date
  updated: string;       // ISO date
  priority?: string;     // e.g., "High", "Medium"
  type?: string;         // e.g., "Story", "Bug"
  labels?: string[];     // Story labels
  comments?: Comment[];  // Story comments
}

Troubleshooting

No stories loaded

• Check your Jira credentials in .env
• Verify the project key is correct
• Ensure your API token has proper permissions

Connection errors

• Verify JIRA_BASE_URL is correct (should be like https://domain.atlassian.net)
• Check if your network can access Jira
• Confirm API token is valid

Stories not updating

• Use the refresh-stories tool to reload from Jira
• Restart the MCP server

Security Notes

• Never commit .env file - It contains sensitive credentials
• Keep your API token secure
• Use environment-specific tokens for different environments
• Regularly rotate API tokens

License

ISC

Support

For issues or questions, please create an issue in the repository.