MCP Jira Integration
A simple Model Context Protocol (MCP) server for Jira that allows LLMs to act as project managers and personal assistants for teams using Jira. Built on the Jira REST API v3.
Features
Core MCP Tools
- create_issue - Create new Jira issues with proper formatting and ADF descriptions
- search_issues - Search issues using JQL with smart formatting and pagination
- get_sprint_status - Get comprehensive sprint progress reports with metrics
- get_team_workload - Analyze team member workloads and capacity
- generate_standup_report - Generate daily standup reports automatically
Project Management Capabilities
- Multi-Project Support: Work with multiple projects by specifying project keys dynamically
- Sprint progress tracking with visual indicators
- Team workload analysis and capacity planning
- Automated daily standup report generation
- Issue creation with proper prioritization
- Smart search and filtering of issues
Reliability
- Automatic retry with exponential backoff on rate limits (429) and transient errors (503)
- Pagination for large result sets
- Timezone-aware date handling
- Graceful handling of custom Jira statuses and issue types
Requirements
- Python 3.8 or higher
- Jira Cloud account with API token
- MCP-compatible client (like Claude Desktop)
Quick Setup
- Clone and install:```bash
git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
2. **Configure Jira credentials**:```bash
cp .env.example .env
# Edit .env with your values
``````env
JIRA_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your.email@domain.com
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123
- Test the server:```bash
.venv/bin/python -m mcp_jira
You should see `Initializing MCP Jira server...` in the output. Press `Ctrl+C` to stop.
## Usage Examples
### Creating Issues
"Create a high priority bug for the login system not working properly"
- Auto-assigns proper issue type, priority, and formatting
### Sprint Management
"What's our current sprint status?"
- Gets comprehensive progress report with metrics and visual indicators
### Team Management
"Show me the team workload for john.doe, jane.smith, mike.wilson"
- Analyzes capacity and provides workload distribution
### Daily Standups
"Generate today's standup report"
- Creates formatted report with completed, in-progress, and blocked items
## MCP Integration
### With Claude Desktop
The config file is located at:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Add the following entry, replacing `/path/to/mcp-jira` with the absolute path where you cloned the repo:```json
{
"mcpServers": {
"mcp-jira": {
"command": "/path/to/mcp-jira/.venv/bin/python",
"args": ["-m", "mcp_jira"]
}
}
}
> Note: Use the Python binary from inside the .venv folder — this ensures all dependencies are available. The cwd field is not required; the server resolves its configuration using absolute paths internally.
To find the correct path, run this from inside the project directory:```bash
echo "$(pwd)/.venv/bin/python"
Restart Claude Desktop after saving the config.
### With Other MCP Clients
The server follows the standard MCP protocol and works with any MCP-compatible client.
## Configuration
### Required Environment Variables
- `JIRA_URL` - Your Jira instance URL
- `JIRA_USERNAME` - Your Jira username/email
- `JIRA_API_TOKEN` - Your Jira API token
- `PROJECT_KEY` - Default project key for operations (can be overridden per request)
### Optional Settings
- `DEFAULT_BOARD_ID` - Default board for sprint operations (can be overridden per request)
- `STORY_POINTS_FIELD` - Custom field ID for Story Points (default: customfield_10026)
- `DEBUG_MODE` - Enable debug logging (default: false)
- `LOG_LEVEL` - Logging level (default: INFO)
## Getting Jira API Token
1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a name and copy the token
4. Use your email as username and the token as password
## Architecture
This implementation prioritizes simplicity and reliability:
- **Single MCP server file** - All tools in one place
- **Standard MCP protocol** - Uses official MCP SDK
- **Jira REST API v3** - Uses Atlassian Document Format (ADF) for descriptions
- **Rich formatting** - Provides beautiful, readable reports
- **Retry with backoff** - Handles rate limits and transient Jira API errors automatically
- **Pagination** - Fetches all results for large issue sets
- **Error handling** - Graceful handling of Jira API issues and custom statuses
- **Async support** - Fast and responsive operations
## Troubleshooting
### Common Issues
1. **"No active sprint found"**
- Make sure your board has an active sprint
- Check that `DEFAULT_BOARD_ID` is set correctly
2. **Authentication errors**
- Verify your API token is correct
- Check that your username is your email address
3. **Permission errors**
- Ensure your Jira user has appropriate project permissions
- Check that the project key exists and you have access
### Debug Mode
Set `DEBUG_MODE=true` in your `.env` file for detailed logging.
## Development
1. Fork the repository
2. Set up a dev environment:```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
- Run tests:
bash python -m pytest tests/ -v - Submit a pull request
License
MIT License - see LICENSE file