# Jira MCP Server 🎫

A Model Context Protocol (MCP) server that integrates with Jira Cloud to provide comprehensive issue management, project tracking, and team collaboration capabilities directly through Claude and other MCP clients.

## Features ✨

### Issue Management
- **Search Issues**: Advanced JQL-based searching with simple filters
- **Get Issue Details**: Comprehensive issue information with comments
- **Create Issues**: Create Stories, Bugs, Tasks, and other issue types
- **Update Issues**: Change status, assignee, priority, and summary
- **Add Comments**: Add comments to existing issues
- **My Issues**: Quick access to your assigned tickets

### Project Management
- **List Projects**: View all accessible projects
- **Project Details**: Get comprehensive project information
- **Issue Types**: See available issue types per project

### Smart Features
- **Flexible User Assignment**: Use 'me', 'myself', or actual usernames/emails
- **Status Transitions**: Automatically handle Jira workflow transitions
- **Rich Text Support**: Handles Atlassian Document Format (ADF)
- **Error Handling**: Comprehensive error messages and validation

## Quick Start 🚀

### 1. Prerequisites
- **Python 3.10 or higher**
- **Claude Desktop** - Download and install from [claude.ai/download](https://claude.ai/download)
- **Access to a Jira Cloud instance**
- **Jira API token** (we'll generate this below)

### 2. Installation

```bash
# Clone this repository
git clone https://github.com/jondoesflow/MCP_Server_JIra.git
cd MCP_Server_JIra

# Install uv (Python package manager) if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Set up virtual environment and install dependencies
$HOME/.local/bin/uv venv
$HOME/.local/bin/uv add "mcp[cli]" httpx python-dotenv
```

### 3. Jira API Setup

1. **Generate an API Token**:
   - Go to [Atlassian Account Security](https://id.atlassian.com/manage-profile/security/api-tokens)
   - Click "Create API token"
   - Give it a name (e.g., "MCP Server")
   - Copy the generated token (save it somewhere safe!)

2. **Create Environment Configuration**:
   ```bash
   # Copy the example environment file
   cp .env.example .env
   ```

3. **Edit the `.env` file**:
   Open the `.env` file in your text editor and fill in your actual values:
   ```env
   # Your Jira Cloud instance URL (without trailing slash)
   JIRA_BASE_URL=https://yourcompany.atlassian.net
   
   # Your Jira account email
   JIRA_EMAIL=your.email@company.com
   
   # Your Jira API token (paste the token you generated above)
   JIRA_API_TOKEN=your_actual_api_token_here
   ```
   
   **Important**: Replace the placeholder values with your actual Jira details!

### 4. Test Your Connection

```bash
# Test your Jira connection before proceeding
$HOME/.local/bin/uv run test_connection.py
```

This should show:
- ✅ Successful login to your Jira instance
- ✅ List of accessible projects
- ✅ Ability to search for issues

If any tests fail, double-check your `.env` file values.

### 5. Configure Claude Desktop

1. **Create the Claude Desktop configuration file**:
   
   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

2. **Add this configuration** (replace `/ABSOLUTE/PATH/TO/` with your actual path):
   ```json
   {
     "mcpServers": {
       "jira": {
         "command": "/Users/yourusername/.local/bin/uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/MCP_Server_JIra",
           "run",
           "jira_server.py"
         ]
       }
     }
   }
   ```

   **To find your absolute path**, run this in the project directory:
   ```bash
   pwd
   ```

3. **Example configuration** (update the username and path):
   ```json
   {
     "mcpServers": {
       "jira": {
         "command": "/Users/jonathanrussell/.local/bin/uv",
         "args": [
           "--directory",
           "/Users/jonathanrussell/Documents/VIbe/MCP/MCP_Server_JIra",
           "run",
           "jira_server.py"
         ]
       }
     }
   }
   ```

### 6. Restart Claude Desktop

**Important**: Completely quit and restart Claude Desktop for the changes to take effect. You should then see MCP tools available in the interface.

## Usage Examples 💡

### Search for Issues
```
"Show me all high priority bugs in the MOBILE project"
"Find issues assigned to me that are in progress"
"Search for issues with 'login' in the title"
```

### Create Issues
```
"Create a bug report for the login timeout issue in project WEB"
"Create a story for implementing dark mode, assign it to me"
"Create a task to update documentation with high priority"
```

### Manage Issues
```
"Move ticket WEB-123 to In Progress"
"Assign ticket MOBILE-456 to john.doe@company.com"
"Add a comment to WEB-123 saying 'Fixed in latest build'"
```

### Project Information
```
"List all available projects"
"Show me details about the MOBILE project"
"What are my current assigned issues?"
```

## Available Tools 🛠️

| Tool | Description |
|------|-------------|
| `search_issues` | Search issues with JQL or simple filters |
| `get_issue` | Get detailed information about a specific issue |
| `get_my_issues` | Get issues assigned to you |
| `create_issue` | Create new issues (Stories, Bugs, Tasks) |
| `update_issue` | Update issue status, assignee, priority, summary |
| `add_comment` | Add comments to issues |
| `list_projects` | List all accessible projects |
| `get_project_info` | Get detailed project information |

## Configuration Options ⚙️

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `JIRA_BASE_URL` | Your Jira Cloud URL (e.g., https://company.atlassian.net) | Yes |
| `JIRA_EMAIL` | Your Jira account email | Yes |
| `JIRA_API_TOKEN` | Your Jira API token | Yes |

### JQL Examples

The server supports full JQL (Jira Query Language) for advanced searching:

```jql
project = "WEB" AND assignee = currentUser() AND status != Done
priority in (High, Highest) AND created >= -7d
issuetype = Bug AND status = "In Progress"
text ~ "login" AND project in (WEB, MOBILE)
```

## Troubleshooting 🔧

### Common Issues

1. **"Missing required environment variables"**
   - Ensure your `.env` file exists and contains all required variables
   - Check that variable names match exactly (case-sensitive)

2. **"Jira API error: 401"**
   - Verify your email and API token are correct
   - Ensure the API token hasn't expired
   - Check that your Jira URL is correct (no trailing slash)

3. **"User not found" when assigning**
   - Use exact email addresses or usernames
   - Try using 'me' to assign to yourself
   - Verify the user has access to the project

4. **"Status not available" when updating**
   - Check available transitions with the error message
   - Jira workflows restrict which status changes are allowed
   - Use exact status names (case-sensitive)

### Debug Mode

To enable detailed logging, modify the logging level in `jira_server.py`:

```python
logging.basicConfig(level=logging.DEBUG)
```

### Testing API Connection

You can test your Jira connection independently:

```bash
# Test API connection
curl -u "your.email@company.com:your_api_token" \
  -H "Accept: application/json" \
  "https://yourcompany.atlassian.net/rest/api/3/myself"
```

## Security Notes 🔒

- **API Tokens**: Never commit your `.env` file to version control
- **Permissions**: The server respects your Jira permissions - you can only access what you normally can
- **Rate Limiting**: The server includes basic rate limiting respect for Jira's API limits
- **HTTPS Only**: Always use HTTPS Jira URLs for secure communication

## Contributing 🤝

This MCP server is designed to be extensible. To add new features:

1. Add new tool functions using the `@mcp.tool()` decorator
2. Follow the existing error handling patterns
3. Update this README with new functionality
4. Test thoroughly with your Jira instance

## License 📄

This project is open source. Feel free to modify and distribute according to your needs.

---

**Need Help?** Check the [MCP Documentation](https://modelcontextprotocol.io/docs) or [Jira REST API Documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).