# jira-minimal-mcp

Minimal MCP server for Jira. Only ~150-1500 tokens vs ~25,000 for official Atlassian MCP.

## Installation

### Docker (recommended)

```bash
docker pull vertliba/jira-minimal-mcp
```

### uv (local)

```bash
uv tool install git+https://github.com/vertliba/jira-minimal-mcp
```

## Usage

### Basic (only get_issue, ~150 tokens)

```bash
docker run -i --rm \
  -e JIRA_URL=https://xxx.atlassian.net \
  -e JIRA_USERNAME=user@example.com \
  -e JIRA_API_TOKEN=xxx \
  vertliba/jira-minimal-mcp
```

### With additional features

```bash
docker run -i --rm \
  -e JIRA_URL=https://xxx.atlassian.net \
  -e JIRA_USERNAME=user@example.com \
  -e JIRA_API_TOKEN=xxx \
  vertliba/jira-minimal-mcp \
  --enable-search --enable-comments
```

### All features (~1500 tokens)

```bash
docker run -i --rm \
  -e JIRA_URL=https://xxx.atlassian.net \
  -e JIRA_USERNAME=user@example.com \
  -e JIRA_API_TOKEN=xxx \
  vertliba/jira-minimal-mcp \
  --enable-all
```

## CLI Arguments

| Argument | Description | Tools |
|----------|-------------|-------|
| (none) | Base functionality | `jira_get_issue` |
| `--enable-search` | JQL queries | `jira_search` |
| `--enable-create` | Create issues | `jira_create_issue` |
| `--enable-update` | Update issues | `jira_update_issue`, `jira_assign_issue` |
| `--enable-comments` | Comments | `jira_add_comment`, `jira_get_comments` |
| `--enable-all` | All tools | All of the above |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `JIRA_URL` | Yes | Jira instance URL (e.g., `https://xxx.atlassian.net`) |
| `JIRA_USERNAME` | Yes | Jira username/email |
| `JIRA_API_TOKEN` | Yes | Jira API token ([create here](https://id.atlassian.com/manage-profile/security/api-tokens)) |

## MCP Client Configuration

### Claude Code (.mcp.json)

```json
{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--network", "host",
        "-e", "JIRA_URL", "-e", "JIRA_USERNAME", "-e", "JIRA_API_TOKEN",
        "vertliba/jira-minimal-mcp", "--enable-search"],
      "env": {
        "JIRA_URL": "https://xxx.atlassian.net",
        "JIRA_USERNAME": "user@example.com",
        "JIRA_API_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

### Codex (config.toml)

```toml
[mcp_servers.jira]
command = "docker"
args = ["run", "-i", "--rm", "--network", "host",
  "-e", "JIRA_URL", "-e", "JIRA_USERNAME", "-e", "JIRA_API_TOKEN",
  "vertliba/jira-minimal-mcp", "--enable-search"]
env = { JIRA_URL = "https://xxx.atlassian.net", JIRA_USERNAME = "user@example.com", JIRA_API_TOKEN = "YOUR_TOKEN" }
```

### Local (uv)

```json
{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "jira-minimal-mcp", "--enable-search"],
      "env": {
        "JIRA_URL": "https://xxx.atlassian.net",
        "JIRA_USERNAME": "user@example.com",
        "JIRA_API_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

## Why?

The official Atlassian MCP server includes 28 tools and consumes ~25,000 tokens of context on every request. This is wasteful if you only need to read issues.

`jira-minimal-mcp` starts with just 1 tool (~150 tokens) and lets you add only what you need.

## License

MIT