Jtk

CI Go Report Card Documentation License

The most comprehensive dedicated Jira MCP server in the open-source ecosystem. A dual-mode Go binary that works as both a rich CLI tool and an MCP server for AI agents.

11 MCP tools · 4 prompt templates · Full CLI · Single binary · Zero dependencies

Why jtk?

	jtk	mcp-atlassian (Python)
Language	Go (single ~15MB binary)	Python (pip install + deps)
Jira tools	11 dedicated tools	~30 mixed Jira+Confluence
Startup	~50ms	~2s
Permission introspection	Dynamic at startup	None
Dev status API	Branches, PRs, commits	Not available
Issue metrics	Cycle time, lead time, time-in-status	Not available
MCP prompts	4 built-in templates	None
Auth	Classic + scoped tokens	Classic only

Features

• Dual Mode — CLI for humans, MCP server for AI agents, same binary
• Git Awareness — Auto-detects Jira issue keys from branch names (e.g., feature/PROJ-123-add-login → PROJ-123)
• Dynamic Permission Introspection — Queries /mypermissions at MCP startup, only registers mutation tools your token allows
• Dev Status API — Surfaces branches, PRs, and commits linked to any issue via Jira's 3-step dev-status endpoint
• Issue Metrics — Cycle time, lead time, time-in-status breakdown with status transition history
• MCP Prompts — Standup summary, sprint status, release notes, dev dependency tree
• Token-Efficient — Consolidated action-based tools minimize schema overhead. ResponseFlattener strips bloated JSON. Full ADF↔Markdown conversion
• Agile-First — Boards, sprints, backlogs, sprint mutations, active sprint detection

Installation

# From source
git clone https://github.com/zach-snell/jtk.git && cd jtk
./install.sh  # builds and copies to ~/.local/bin

# Or build manually
go build -o jtk ./cmd/jtk

Pre-built binaries available on the Releases page.

Quick Start

# Authenticate
jtk auth

# Get current issue from git branch
jtk issues get

# Search with JQL
jtk issues search --jql "project = PROJ AND status = 'In Progress'"

# Create an issue
jtk issues create --project PROJ --type Task --summary "Fix login bug"

# Sprint overview
jtk boards list
jtk boards active-sprint --board 1

CLI Commands

jtk auth                    Authenticate with Jira Cloud
jtk issues                  Issue CRUD, search, comments, transitions, links
jtk boards                  Agile boards, sprints, backlogs
jtk projects                List, get, create projects
jtk users                   Search and get users
jtk versions                Project versions/releases
jtk worklogs                Time tracking

MCP Server

Stdio Transport (Claude Desktop, Cursor, OpenCode, etc.)

{
  "mcpServers": {
    "jira": {
      "command": "/path/to/jtk",
      "args": ["mcp"],
      "env": {
        "JIRA_DOMAIN": "your-domain",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Streamable HTTP Transport

jtk mcp --port 8080

Environment Variables

Variable	Description	Required
JIRA_DOMAIN	Atlassian domain (e.g., acme for acme.atlassian.net)	Yes
JIRA_EMAIL	Email for the API token	Yes
JIRA_API_TOKEN	Atlassian API token	Yes
JIRA_TOKEN_TYPE	classic or scoped (auto-detected if omitted)	No
JIRA_DISABLED_TOOLS	Comma-separated tool names to hide	No

MCP Tools (11)

Tool	Actions
manage_issues	get, create, update, assign, transition, delete, add_comment, edit_comment, list_comments, list_types, get_links, get_history, link, list_link_types, get_watchers, add_watcher, remove_watcher
manage_search	jql, quick
manage_boards	list_boards, get_board, list_sprints, get_sprint_issues, get_backlog, get_active_sprint, search_sprints, create_sprint, update_sprint, move_to_sprint
manage_projects	list, get, list_statuses, create
manage_devinfo	get_dev_info
manage_worklogs	list, add
manage_versions	list, get, create
manage_attachments	list, download, upload, delete
manage_users	get_current, search, get
manage_metrics	get_dates, get_metrics

MCP Prompts (4)

Prompt	Description
standup_summary	Generate a standup report from recent activity
sprint_status	Analyze sprint health and progress
release_notes	Draft release notes from a version's issues
dev_dependency_tree	Map development dependencies across linked issues

Security

Three-layer safety model:

1. Token scopes — Atlassian scopes control which APIs the token can call (403 if missing)
2. Permission introspection — jtk queries /mypermissions at startup and dynamically hides mutation tools your account lacks
3. Tool denial — Explicitly hide tools: JIRA_DISABLED_TOOLS="manage_boards,manage_worklogs"

Token scopes — use classic

When creating an API token with scopes, prefer classic scopes for full read + write:

read:jira-user,read:jira-work,write:jira-work,manage:jira-project

(Read-only: read:jira-user,read:jira-work.) jtk auto-detects the token type, so granular scopes also work — but granular is Beta and finicky: "fat" endpoints require every satellite scope (e.g. /myself needs read:user + read:avatar + read:group + read:application-role), and granular personal API tokens currently return 401 Unauthorized; scope does not match on POST requests through the gateway, making them effectively read-only. jtk auth prints copy-paste scope lists for both.

Development

go test -race ./...          # Run tests
golangci-lint run ./...      # Lint
go build -o jtk ./cmd/jtk   # Build

License

Apache 2.0