# Jira MCP

MCP server for Jira ticket context via REST API — read issues, search, post comments with @mentions.

## Project Structure

```
jira-mcp/
  .env                  # credentials (not committed)
  config.env.example    # template for .env
  docker-compose.yml    # Docker SSE mode
  Dockerfile
  run.py                # entry point
  requirements.txt
  jira_mcp/
    __init__.py
    config.py           # JiraConfig + ServerConfig from env
    jira_client.py      # Jira REST API client
    server.py           # FastMCP server + tool registration
```

## Tools

| Tool | Params | Description |
|---|---|---|
| `get_jira_issue` | `issue_key` | Full ticket details: summary, status, type, priority, assignee, reporter, created, updated, labels, parent, subtasks, linked issues, rendered description |
| `get_jira_issue_comments` | `issue_key`, `limit` (default 20) | Comments with id, author, created, rendered body |
| `search_jira_issues` | `jql`, `limit` (default 10) | Search issues by JQL, returns key/summary/type/status/priority/assignee |
| `add_jira_comment` | `issue_key`, `body`, `mentioned_users` (comma-separated names) | Post a comment, optionally @mention users |
| `search_jira_users` | `query`, `limit` (default 10) | Find users by name/email, returns accountId/displayName/emailAddress |

## Configuration

Copy `config.env.example` to `.env` and fill in:

```env
JIRA_SITE=your-site.atlassian.net
JIRA_EMAIL=your_email@example.com
JIRA_TOKEN=your_api_token
MCP_TRANSPORT=sse
MCP_SERVER_PORT=8080
```

| Variable | Default | Description |
|---|---|---|
| `JIRA_SITE` | (required) | Jira Cloud site hostname |
| `JIRA_EMAIL` | — | Email for basic auth |
| `JIRA_TOKEN` | — | API token (https://id.atlassian.com/manage-profile/security/api-tokens) |
| `MCP_TRANSPORT` | `sse` | Transport: `sse` (HTTP) or `stdio` |
| `MCP_SERVER_PORT` | `8080` | HTTP port (sse transport only) |

## Running

### SSE mode (Docker)

```bash
docker compose up -d --build
```

Container `jira-mcp` listens on `localhost:8007/mcp`.

### Stdio mode (local)

```bash
MCP_TRANSPORT=stdio python run.py
```

No Docker needed. Communicates via stdin/stdout.

## OpenCode Config

Example config files are provided: `opencode.sse.json` and `opencode.stdio.json`.

### Remote (SSE via Docker)

```json
{
    "mcp": {
        "jira": {
            "type": "remote",
            "url": "http://localhost:8007/mcp",
            "enabled": true
        }
    }
}
```

### Local (stdio subprocess)

```json
{
    "mcp": {
        "jira": {
            "type": "local",
            "command": ["python", "/path/to/jira-mcp/run.py"],
            "enabled": true,
            "environment": {
                "MCP_TRANSPORT": "stdio",
                "JIRA_SITE": "your-site.atlassian.net",
                "JIRA_EMAIL": "your_email@example.com",
                "JIRA_TOKEN": "your_api_token"
            }
        }
    }
}
```

## Adding New Tools

1. Add the method to `jira_mcp/jira_client.py` (API logic)
2. Register in `jira_mcp/server.py` via `self.server.tool()` decorator
3. Rebuild container: `docker compose up -d --build`