Configuration

Authentication

jtk supports two authentication methods: interactive login and environment variables.

Interactive Login

jtk auth

You will be prompted for your Jira domain, email, and API token. The command also prints the exact granular scopes to select when creating your token.

Credentials are saved to ~/.config/jtk/credentials.json with restricted file permissions.

API Token Scopes

Create a Jira app token at id.atlassian.com. Select “Jira” as the app, then add granular scopes.

Read-only (18 scopes)

read:me
read:jql:jira
read:issue-details:jira
read:issue-type:jira
read:issue-link:jira
read:issue-worklog:jira
read:issue.changelog:jira
read:issue.transition:jira
read:comment:jira
read:attachment:jira
read:project:jira
read:project-version:jira
read:status:jira
read:user:jira
read:permission:jira
read:board-scope:jira-software
read:sprint:jira-software
read:dev-info:jira

Full access (add 7 more)

write:issue:jira
write:comment:jira
write:issue-worklog:jira
write:issue-link:jira
write:attachment:jira
write:sprint:jira-software
delete:issue:jira

Tip

jtk provides a two-layer safety model: token scopes control API access (403 if missing), and /mypermissions introspection dynamically hides mutation tools your Jira account lacks.

Check your auth status:

jtk status

Log out and remove stored credentials:

jtk logout

Environment Variables

For CI/CD or ephemeral environments, set these environment variables:

export JIRA_DOMAIN="mycompany"
export JIRA_EMAIL="me@example.com"
export JIRA_API_TOKEN="ATATT3x..."

Environment variables take priority over stored credentials.

Credentials File Format

{
  "domain": "mycompany",
  "email": "me@example.com",
  "api_token": "ATATT3x...",
  "saved_at": "2025-01-15T10:30:00Z"
}

Caution

Never commit credentials to version control. The credentials.json file is saved with 0600 permissions (owner read/write only).

MCP Client Configuration

To use jtk as an MCP server, configure your AI client:

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jtk": {
      "command": "jtk",
      "args": ["mcp"]
    }
  }
}

Claude Code

claude mcp add jtk -- jtk mcp

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "jtk": {
      "command": "jtk",
      "args": ["mcp"]
    }
  }
}

Environment Variables

If you prefer environment variables over stored credentials:

{
  "mcpServers": {
    "jtk": {
      "command": "jtk",
      "args": ["mcp"],
      "env": {
        "JIRA_DOMAIN": "mycompany",
        "JIRA_EMAIL": "me@example.com",
        "JIRA_API_TOKEN": "ATATT3x..."
      }
    }
  }
}

Disabling Tools

You can disable specific MCP tools via the JIRA_DISABLED_TOOLS environment variable:

export JIRA_DISABLED_TOOLS="manage_worklogs,manage_attachments"

Or in your MCP client config:

{
  "mcpServers": {
    "jtk": {
      "command": "jtk",
      "args": ["mcp"],
      "env": {
        "JIRA_DISABLED_TOOLS": "manage_worklogs,manage_attachments"
      }
    }
  }
}