# MCP Server for JIRA

A Model Context Protocol (MCP) server that provides seamless integration with Jira. This server enables AI assistants to retrieve issue information, comments, and attachments from any Jira instance.

## Features

- 🎫 **Issue Management**: Get, create, update, and transition issues
- 🔍 **Advanced Search**: JQL-based issue search with custom fields
- 📊 **Epic & Sprint Tracking**: Monitor progress, story points, and completion
- 🔗 **Issue Relationships**: View and manage issue links
- 💬 **Comments**: Add and retrieve issue comments
- 📎 **Attachments**: Download issue attachments
- 📜 **History**: Track all changes to issues
- 🚀 **Release Management**: View project versions and releases
- 👥 **Assignment**: Assign/unassign issues to users
- 🔒 **Secure Authentication**: Uses Jira API tokens

## Installation

### Using uvx (Recommended)

```bash
uvx jira-mcp-tools
```

### Using pip

```bash
pip3 install jira-mcp-tools
```

## Prerequisites

- Python 3.10 or higher
- Jira API token ([How to create](https://jsw.ibm.com/plugins/servlet/de.resolution.apitokenauth/admin))
- UV package manager ([Installation guide](https://docs.astral.sh/uv/getting-started/installation/))

## Configuration

### Environment Variables

The server requires three environment variables:

- `JIRA_URL`: Your Jira instance URL
- `JIRA_EMAIL`: Your Jira account email
- `JIRA_TOKEN`: Your Jira API token

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Bob):

```json
{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["jira-mcp-tools"],
      "env": {
        "JIRA_URL": "https://jsw.ibm.com/",
        "JIRA_EMAIL": "your-email@ibm.com",
        "JIRA_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Available Tools

### Issue Information

#### `get_jira_ticket_info`
Get detailed information about a Jira issue including description and comments.

**Parameters:**
- `issue_key` (string): Issue key (e.g., "PROJ-123")

**Example:** `get_jira_ticket_info("PROJ-123")`

#### `get_jira_ticket_attachments`
Download attachments from a Jira issue.

**Parameters:**
- `issue_key` (string): Issue key

**Example:** `get_jira_ticket_attachments("PROJ-456")`

#### `get_issue_history`
Get complete change history of an issue including status transitions and field updates.

**Parameters:**
- `issue_key` (string): Issue key

**Example:** `get_issue_history("PROJ-123")`

#### `get_issue_links`
Get all linked issues (blocks, relates to, etc.).

**Parameters:**
- `issue_key` (string): Issue key

**Example:** `get_issue_links("PROJ-123")`

### Search & Discovery

#### `search_issues`
Search for issues using JQL (Jira Query Language).

**Parameters:**
- `jql` (string): JQL query (e.g., 'project = PROJ AND status = "In Progress"')
- `max_results` (int, optional): Maximum results (default: 50)
- `fields` (string, optional): Comma-separated field list

**Examples:**
```python
search_issues('project = MYPROJ')
search_issues('assignee = currentUser() AND status != Done')
search_issues('updated >= -7d ORDER BY updated DESC')
```

### Epic & Sprint Management

#### `get_epic_details`
Get epic information including child issues, progress metrics, and story points.

**Parameters:**
- `epic_key` (string): Epic issue key

**Example:** `get_epic_details("PROJ-123")`

#### `get_sprint_info`
Get sprint information for a board.

**Parameters:**
- `board_id` (int): Jira board ID
- `sprint_id` (int, optional): Specific sprint ID (omit for all sprints)

**Examples:**
```python
get_sprint_info(42)  # All sprints for board 42
get_sprint_info(42, 123)  # Specific sprint
```

### Project Management

#### `get_project_releases`
Get all releases/versions for a project with associated issues.

**Parameters:**
- `project_key` (string): Project key (e.g., "PROJ")

**Example:** `get_project_releases("PROJ")`

### Issue Modification

#### `create_issue`
Create a new Jira issue.

**Parameters:**
- `project_key` (string): Project key
- `summary` (string): Issue title
- `description` (string): Issue description
- `issue_type` (string, optional): Issue type (default: "Task")

**Example:** `create_issue("PROJ", "Fix bug", "Description here", "Bug")`

#### `update_issue`
Update fields of an existing issue.

**Parameters:**
- `issue_key` (string): Issue key
- `fields` (dict): Fields to update

**Examples:**
```python
update_issue("PROJ-123", {"summary": "New title"})
update_issue("PROJ-123", {"priority": {"name": "High"}})
update_issue("PROJ-123", {"labels": ["bug", "urgent"]})
```

#### `transition_issue`
Move an issue to a new status.

**Parameters:**
- `issue_key` (string): Issue key
- `transition_name` (string): Transition name (e.g., "In Progress", "Done")

**Example:** `transition_issue("PROJ-123", "In Progress")`

#### `assign_issue`
Assign an issue to a user.

**Parameters:**
- `issue_key` (string): Issue key
- `assignee` (string): Username/email (use "none" to unassign)

**Example:** `assign_issue("PROJ-123", "user@company.com")`

#### `add_comment`
Add a comment to an issue.

**Parameters:**
- `issue_key` (string): Issue key
- `comment_text` (string): Comment text

**Example:** `add_comment("PROJ-123", "This is a comment")`

## Development

### Local Development Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd mcp-jira
   ```

2. **Install dependencies**
   ```bash
   uv sync
   ```

3. **Configure environment**
   ```bash
   cp env.template .env
   # Edit .env with your Jira credentials:
   # JIRA_URL=https://your-instance.atlassian.net/
   # JIRA_EMAIL=your-email@company.com
   # JIRA_TOKEN=your-api-token
   ```

4. **Run the server**
   ```bash
   uv run mcp_jira/server.py
   ```

### Testing with Bob

1. **Add to Bob's MCP settings** (`~/.bob/mcp_settings.json` or via Bob UI):
   ```json
   {
     "mcpServers": {
       "jira": {
         "command": "uv",
         "args": ["--directory", "/path/to/mcp-jira", "run", "mcp_jira/server.py"],
         "env": {
           "JIRA_URL": "https://your-instance.atlassian.net/",
           "JIRA_EMAIL": "your-email@company.com",
           "JIRA_TOKEN": "your-api-token"
         }
       }
     }
   }
   ```

2. **Restart Bob** to load the MCP server

3. **Switch to Advanced mode** in Bob to access MCP tools

4. **Test the connection**:
   - Ask Bob: "Search for issues in project PROJ"
   - Or: "Get details for issue PROJ-123"

### Running Tests

```bash
# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov
```

## Use Cases

- **AI-Assisted Development**: Let AI assistants fetch and analyze Jira issues
- **Automated Workflows**: Integrate Jira data into automated processes
- **Context-Aware Coding**: Provide issue context to AI coding assistants
- **Documentation**: Auto-generate documentation from Jira issues

## Roadmap

- [ ] Support for creating and updating issues
- [ ] Advanced search capabilities
- [ ] Support for Jira workflows and transitions
- [ ] Enhanced attachment handling (PDFs, images)
- [ ] Bulk operations support

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/IBM/mcp-jira/issues)
- **Documentation**: [Full Documentation](https://github.com/IBM/mcp-jira)

## Acknowledgments

Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - Fast MCP server framework
- [jira-python](https://github.com/pycontribs/jira) - Python Jira library
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
