# 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

1. **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
```

3. **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](https://id.atlassian.com/manage-profile/security/api-tokens)
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]"
```
3. Run tests:
```bash
python -m pytest tests/ -v
```
4. Submit a pull request

## License

MIT License - see LICENSE file