# 🔌 Jira MCP Integration

**Cursor AI and other agents write amazing code.** In enterprises, tasks are given in instruments like Jira, GitHub Issues, Azure DevOps. AI needs access to such instruments.

This open-source solution helps AI agents work with Jira data.

## 🌐 Public Instance

**Available at https://jira-mcp.koveh.com**

Just provide your Jira credentials. We don't store any data.

## Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   AI Agent      │────▶│   MCP Server    │────▶│   Jira Cloud    │
│  (Cursor/etc)   │◀────│   jira-mcp      │◀────│   REST API      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

## Features

- ✅ Get list of projects
- ✅ Get list of tasks with details
- ✅ Get specific task with descriptions
- ✅ Create new tickets
- ✅ Update existing tickets
- ✅ Delete tickets
- ✅ Search using JQL
- ✅ Assign tasks to users
- ✅ Transition task status

## Quick Start

### Option 1: Use Public Instance

Go to **https://jira-mcp.koveh.com** and connect with your Jira credentials.

### Option 2: Run with Docker

```bash
git clone https://github.com/Koveh/jira-mcp.git
cd jira-mcp
docker-compose up -d
```

Access at http://localhost:4200

### Option 3: Run Locally

```bash
git clone https://github.com/Koveh/jira-mcp.git
cd jira-mcp
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python http_server.py
```

## Get Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the token

## Usage

### Add to Cursor IDE (Local MCP)

1. Clone and set up virtual environment:
```bash
git clone https://github.com/Koveh/jira-mcp.git
cd jira-mcp

# Create virtual environment (required for mcp package)
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

2. Get your Jira API token from: https://id.atlassian.com/manage-profile/security/api-tokens

3. Add to `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):

```json
{
  "mcpServers": {
    "jira": {
      "command": "/full/path/to/jira-mcp/venv/bin/python",
      "args": ["/full/path/to/jira-mcp/mcp_server.py"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token-from-step-2"
      }
    }
  }
}
```

> **Important:** Use the full path to the Python interpreter inside the venv (`venv/bin/python` on Linux/macOS, `venv\Scripts\python.exe` on Windows). This ensures the `mcp` package is available.

4. Restart Cursor (Cmd/Ctrl+Shift+P → "Developer: Reload Window")

You'll have these tools available:

| Tool | Description |
|------|-------------|
| `jira_connect` | Connect to Jira instance |
| `jira_get_projects` | List all projects |
| `jira_get_issues` | Get issues from project |
| `jira_get_issue` | Get specific issue details |
| `jira_create_issue` | Create new issue |
| `jira_update_issue` | Update existing issue |
| `jira_delete_issue` | Delete issue |
| `jira_search` | Search with JQL |
| `jira_get_current_user` | Get current user info |

### REST API Usage

```bash
# 1. Connect and get token
curl -X POST https://jira-mcp.koveh.com/api/connect \
  -H "Content-Type: application/json" \
  -d '{
    "base_url": "https://your-domain.atlassian.net",
    "email": "your-email@example.com",
    "api_token": "your-api-token"
  }'

# Response includes token for subsequent requests
# {"status": "connected", "token": "eyJ...", ...}

# 2. Use token for API calls
curl https://jira-mcp.koveh.com/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Create issue
curl -X POST https://jira-mcp.koveh.com/api/issues \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": "PROJ", "summary": "New task"}'
```

### CLI Usage

```bash
export JIRA_BASE_URL=https://your-domain.atlassian.net
export JIRA_EMAIL=your-email@example.com
export JIRA_API_TOKEN=your-api-token

python cli.py whoami                    # Show current user
python cli.py projects                  # List projects
python cli.py list PROJ                 # List issues
python cli.py get PROJ-123              # Get issue details
python cli.py create PROJ "Summary"     # Create issue
python cli.py update PROJ-123 -s "New"  # Update issue
python cli.py delete PROJ-123           # Delete issue
python cli.py search "status='Done'"    # Search with JQL
```

### Python Client

```python
from jira_client import JiraClient, JiraConfig

config = JiraConfig(
    base_url="https://your-domain.atlassian.net",
    email="your-email@example.com",
    api_token="your-api-token"
)

client = JiraClient(config)

# Get projects
projects = client.get_all_projects()

# Create issue
issue = client.create_issue("PROJ", "Summary", "Description")

# Search
results = client.search_issues("status = 'In Progress'")
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| POST | `/api/connect` | Connect and get token |
| GET | `/api/user` | Get current user |
| GET | `/api/projects` | List all projects |
| GET | `/api/issues?project=KEY` | Get project issues |
| GET | `/api/issue/KEY` | Get issue details |
| POST | `/api/issues` | Create issue |
| PUT | `/api/issue/KEY` | Update issue |
| DELETE | `/api/issue/KEY` | Delete issue |
| GET | `/api/search?jql=...` | Search with JQL |

## Project Structure

```
jira-mcp/
├── jira_client.py      # Core Jira API wrapper
├── mcp_server.py       # MCP server (stdio transport)
├── http_server.py      # HTTP/REST server
├── cli.py              # Command-line interface
├── Dockerfile          # Docker image
├── docker-compose.yml  # Docker Compose config
├── requirements.txt    # Python dependencies
├── examples/           # Usage examples
│   ├── cursor_mcp_config.json
│   └── api_usage.sh
└── tests/              # Test scripts
    ├── test_jira.py
    └── demo.py
```

## Self-Hosting with Docker

```bash
# Build and run
docker-compose up -d

# Or manually
docker build -t jira-mcp .
docker run -d -p 4200:4200 --name jira-mcp jira-mcp
```

### With nginx reverse proxy

```nginx
server {
    server_name jira-mcp.yourdomain.com;
    
    location / {
        proxy_pass http://127.0.0.1:4200;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

### SSL with Certbot

```bash
certbot --nginx -d jira-mcp.yourdomain.com
```

## Security

- 🔒 We don't store any credentials or data
- 🔑 Credentials are only used for direct Jira API calls
- 📤 Use API tokens (not passwords)
- 🔄 Tokens can be revoked anytime at id.atlassian.com

## License

MIT

## Author

**DHW Team** - [koveh.com](https://koveh.com)

---

Made with ❤️ for the AI-powered development community