# 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/).
