Jira Stories MCP Server

# 📊 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 Search**JIRA_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 ````bash **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 ```bash npm run build ``` ### Run in Development Mode ```bash # Stdio mode npm run dev # HTTP mode npm run dev:http ``` ### Inspect with MCP Inspector ```bash npm run inspect ``` ## API Reference ### Story Object Structure ```typescript { 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.