keen

Keen

The complete Atlassian platform CLI and MCP Server.

[Release] [Apache 2.0 License] [Go Version] [CI] [Go Report Card]

[Imogen Labs]

1,843 API endpoints across Jira, Confluence, Agile, Marketplace, Service Desk, Assets, Compass, Bitbucket and Admin — in a single Go binary. SQLite-backed local sync with full-text search. MCP server for AI agents. Built for automation first, humans second.

What is Keen?

Every Atlassian workflow you automate is a wall of curl calls with hand-rolled JSON payloads and fragile jq parsing. Every AI agent that touches Jira hits rate limits after a few dozen operations.

Keen replaces all of that with typed commands, structured output, local SQLite caching with FTS5 full-text search, and an MCP server that gives AI agents fast, uncapped access to your entire Atlassian stack.

Free and open source. Apache-2.0 license. No account required. No telemetry.

API Coverage

Your First 5 Minutes

# 1. Install (macOS or Linux with Homebrew; see Install for .deb, .rpm and Docker)brew install imogenlabs/tap/keen
# 2. Save your credentialsmkdir -p ~/.config/keencat > ~/.config/keen/auth.json <<'JSON'{ "base_url": "https://yoursite.atlassian.net", "username": "[email protected]", "password": "your-api-token" }JSONchmod 600 ~/.config/keen/auth.json
# 3. Check connectivitykeen doctor
# 4. Sync your Jira data locallykeen sync
# 5. Search instantly (no API calls)keen search "authentication bug" --data-source local

Generate an API token at id.atlassian.com/manage-profile/security/api-tokens.

Environment variables work too, and override the file:

export JIRA_CLOUD_PLATFORM_USERNAME="[email protected]"export JIRA_CLOUD_PLATFORM_PASSWORD="your-api-token"export JIRA_CLOUD_PLATFORM_URL="https://yoursite.atlassian.net"

Install

Homebrew (macOS and Linux)

brew install imogenlabs/tap/keen

This installs both keen and keen-mcp. brew upgrade keen picks up new releases; the formula follows each release within a day.

Debian, Ubuntu, Fedora, RHEL

Each release has .deb and .rpm packages for x86_64 (amd64) and arm64. They install keen and keen-mcp in /usr/bin.

# Debian, Ubuntucurl -LO https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_amd64.debsudo apt install ./keen_linux_amd64.deb
# Fedora, RHELcurl -LO https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_amd64.rpmsudo dnf install ./keen_linux_amd64.rpm

On arm64, use keen_linux_arm64.deb or keen_linux_arm64.rpm. To upgrade, install the new release's package the same way.

Docker

The image is on GitHub's registry and Docker Hub, for amd64 and arm64: ghcr.io/imogenlabs/keen or smashingtags/keen. It runs keen-mcp by default. To run the CLI, put keen and its arguments after the image name:

docker run --rm \  -e JIRA_CLOUD_PLATFORM_URL=https://yoursite.atlassian.net \  -e [email protected] \  -e JIRA_CLOUD_PLATFORM_PASSWORD=your-api-token \  ghcr.io/imogenlabs/keen keen get PROJ-42 --agent

Add -v keen-data:/home/nonroot to keep keen sync's local copy between runs. To use it as an MCP server, see Docker under MCP Server.

Binary download

Download from GitHub Releases:

# macOS (Apple Silicon)curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_darwin_arm64.tar.gz | tar xzsudo mv keen_darwin_arm64/keen /usr/local/bin/sudo mv keen_darwin_arm64/keen-mcp /usr/local/bin/
# macOS (Intel)curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_darwin_amd64.tar.gz | tar xzsudo mv keen_darwin_amd64/keen /usr/local/bin/sudo mv keen_darwin_amd64/keen-mcp /usr/local/bin/
# Linux (x86_64)curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_amd64.tar.gz | tar xzsudo mv keen_linux_amd64/keen /usr/local/bin/sudo mv keen_linux_amd64/keen-mcp /usr/local/bin/
# Linux (arm64)curl -L https://github.com/imogenlabs/keen/releases/latest/download/keen_linux_arm64.tar.gz | tar xzsudo mv keen_linux_arm64/keen /usr/local/bin/sudo mv keen_linux_arm64/keen-mcp /usr/local/bin/

Each release also publishes checksums.txt.

From source

git clone https://github.com/imogenlabs/keen.gitcd keenmake build-all   # builds bin/keen and bin/keen-mcp

Requires Go 1.26.10 or newer.

What changed in each release: CHANGELOG.md.

MCP Server

Keen includes an MCP server (keen-mcp) that gives AI agents every keen command (1,939 tools). Works with Claude Code, Cursor, Windsurf, and any MCP-compatible host.

It offers two tools: keen_search finds the tools for a task ("transition an issue", "list sprints on a board") and returns them with their parameters, and keen_run runs one by name. Listing all 1,939 tools one by one would take about half a million tokens, more than most models can hold, so an app connecting to keen would fill up before doing any work. To get the full list anyway, set KEEN_MCP_TOOLS=all in the server's environment.

Tool calls arrive as JSON-RPC over stdio. Finding a tool happens inside keen-mcp with no call to Atlassian. Running one goes to Atlassian, except that a read repeated within 5 minutes is answered from keen's cache, so a busy agent stays under Atlassian's rate limits. Any successful write clears the cache, so a read after a write is fresh. Set KEEN_MCP_CACHE=off to make every read live. If a tool's API has been switched off by Atlassian, the result says what to use instead.

[MCP request flow: the AI app asks keen_search for a task in plain words and gets the best matching tools back without any call to Atlassian, then calls keen_run, which answers a recent repeat read from keen's cache and sends everything else to Atlassian.]

Source: docs/diagrams/mcp-flow.drawio.

Claude Desktop, and the MCP registry

On a Mac, download keen-mcp.mcpb from the latest release and open it: Claude Desktop installs keen and asks for your Atlassian site, email and API token. keen is also listed in the official MCP registry as io.github.imogenlabs/keen, updated with every release.

keen-mcp finds credentials the same way the CLI does: environment variables first, then ~/.config/keen/auth.json or config.toml. If you already set up the CLI, claude mcp add --transport stdio keen -- keen-mcp is enough. To pass them explicitly instead:

Claude Code

claude mcp add --transport stdio keen \  --env [email protected] \  --env JIRA_CLOUD_PLATFORM_PASSWORD=your-api-token \  --env JIRA_CLOUD_PLATFORM_URL=https://yoursite.atlassian.net \  -- keen-mcp

Cursor

Add to .cursor/mcp.json:

{  "mcpServers": {    "keen": {      "command": "keen-mcp",      "env": {        "JIRA_CLOUD_PLATFORM_USERNAME": "[email protected]",        "JIRA_CLOUD_PLATFORM_PASSWORD": "your-api-token",        "JIRA_CLOUD_PLATFORM_URL": "https://yoursite.atlassian.net"      }    }  }}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json with the same structure.

Docker

Any MCP host can run keen-mcp from the image instead of installing it. The -e NAME flags pass the values from env into the container:

{  "mcpServers": {    "keen": {      "command": "docker",      "args": ["run", "-i", "--rm",               "-e", "JIRA_CLOUD_PLATFORM_URL", "-e", "JIRA_CLOUD_PLATFORM_USERNAME", "-e", "JIRA_CLOUD_PLATFORM_PASSWORD",               "ghcr.io/imogenlabs/keen"],      "env": {        "JIRA_CLOUD_PLATFORM_URL": "https://yoursite.atlassian.net",        "JIRA_CLOUD_PLATFORM_USERNAME": "[email protected]",        "JIRA_CLOUD_PLATFORM_PASSWORD": "your-api-token"      }    }  }}

Local Sync & Offline Search

Keen syncs your Atlassian data to a local SQLite database with FTS5 full-text search. Queries run in under 100ms against the local cache instead of hitting the Jira Cloud API.

keen sync                                          # hydrate local cachekeen search "sprint bug" --data-source local        # FTS search (sub-100ms)keen analytics                                      # analytics on synced datakeen stale --days 30                                # find stale itemskeen orphans                                        # find orphaned itemskeen load                                           # workload distribution

This is especially useful for AI agents that need to make many queries without hitting Atlassian's rate limits.

Agent Mode

Every command supports --agent which sets JSON output, no interactive prompts, compact format, and no color in one flag. Designed for AI agent consumption.

keen agile get-all-boards --agentkeen issue transitions get PROJ-42 --agent | jq '.results.transitions[] | {id, name}'

The everyday Jira calls have short forms:

keen find-issues --jql "project = PROJ AND status = 'In Progress'" --agentkeen get PROJ-42 --agentkeen transition PROJ-42 --transition-name "In Progress" --agent   # name resolved to its idkeen sprints 42 --state active --agent

To start work on an issue, one call gets everything around it, kept under a token budget:

keen context PROJ-42 --org my-org --agent              # default --budget 8000

It returns the issue, its parent, comments, linked issues, sub-tasks, GitHub pull requests and commits (see GitHub Work for an Issue) and linked Confluence pages. The issue comes first, then the parent, GitHub work, linked issues and sub-tasks, the newest comments, Confluence pages and older comments. Whatever does not fit is listed under budget.omitted with its size, never dropped silently.

Key Flags

Command Discovery

keen which "transition an issue"   # the command for a task, in plain wordskeen which "create page"           # one line per answer; "no match" when nothing fitskeen api                     # browse all API interfaceskeen api wiki                # browse Confluence endpointskeen api agile               # browse Agile endpoints

Common Workflows

Sprint Management

keen agile get-all-boards --agentkeen agile get-all-sprints BOARD_ID --state active,future --agentkeen agile create-sprint --stdin <<< '{"name":"Sprint 5","originBoardId":42}'keen agile move-issues-to-sprint-and-rank SPRINT_ID \  --stdin <<< '{"issues": ["PROJ-42", "PROJ-43"]}'keen agile partially-update-sprint SPRINT_ID --stdin <<< '{"state": "active"}'

Release Tracking

Record git release tags as Jira versions and tag the issues they shipped:

# every release tag so far, plus an unreleased "next" for work merged sincekeen release sync --repo-path . --project PROJ --backfill --head origin/main --dry-run# after publishing a release: "next" becomes the tag, a fresh "next" is createdkeen release sync --repo-path . --project PROJ --tag v1.4.0 --head origin/main

A version is named as the tag, released on the tag's commit date and linked to its GitHub release. An issue gets the first release whose commits name its key as a Fix Version; existing Fix Versions are added to, never replaced.

GitHub Work for an Issue

Put the issue key in branch names, commit messages and PR titles, the way Atlassian links them (fix/PROJ-42-retry-uploads, fix: PROJ-42 retry failed uploads). Then:

keen github links PROJ-42 --org my-org     # or --repo my-org/api, or run it inside a checkout

lists every pull request and commit for the issue once, with where it was found: Jira's development panel (when the GitHub for Jira app is connected), GitHub search for the key, and web links on the issue that point at a PR. GitHub search uses KEEN_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN or your gh login. A source that is not set up is a warning, not a failure.

Issue Lifecycle

keen jira-cloud-platform-search and-reconsile-issues-using-jql-post \  --jql "project = PROJ AND status != Done" --agentkeen issue transitions get PROJ-42 --agentkeen issue transitions do PROJ-42 --transition-id 41 --agentkeen issue comment add PROJ-42 --body "Done."    # plain text is wrapped into ADF

Confluence

keen wiki search-content-by-cql --cql "type=page AND space=DOCS" --agentkeen wiki create-page --space DOCS --title "Release notes" --stdin < notes.xhtmlkeen wiki update-page PAGE_ID --stdin < notes.xhtml   # version bumped for youkeen wiki get-page PAGE_ID --agentkeen wiki get-content-descendants PAGE_ID --agentkeen wiki add-labels-to-content PAGE_ID --stdin <<< '[{"prefix":"global","name":"adr"}]'

Page bodies are Confluence storage format (XHTML); Markdown is not converted.

Marketplace

keen addons get io.example.my-addon --agentkeen addons list-search --q "story points" --agentkeen addons versions get io.example.my-addon --agent

Comparison

More detail, and when to pick something else: Comparison.

Architecture

The keen CLI and the keen-mcp server share one set of commands over 1,843 REST endpoints and 18 GraphQL queries. Calls go to Atlassian, with repeat reads within 5 minutes answered from a short response cache that every write clears. keen sync copies data into a local SQLite + FTS5 store, which keen search and offline reads (--data-source local, or automatically when Atlassian cannot be reached) use.

[Keen architecture: the keen CLI and keen-mcp server share one set of commands that call Atlassian through an HTTP client (REST and GraphQL) with a short response cache, with a local SQLite + FTS5 store filled by sync for search and offline reads. Atlassian Cloud APIs: Jira Platform, Jira Agile, Confluence v1 and v2, Marketplace, Service Desk, Admin, Assets, Compass, Bitbucket, and Teamwork Graph.]

Source: docs/diagrams/architecture.drawio (editable in draw.io).

Regeneration

keen is generated from 15 official Atlassian OpenAPI specs (in specs/) by CLI Printing Press, then carries its own changes on top. The list of specs lives in one place, SPECS in scripts/regen/config.sh. One script refreshes keen from Atlassian's current specs without losing those changes:

git switch -c build/refresh-specsscripts/regen/regen.sh        # download current specs, generate, merge onto keenscripts/regen/check.sh        # build, tests, lint, vulnerabilities, old-name and help checks

How it works: the generator's previous output (renamed to keen) is kept on GitHub as the hidden ref refs/regen/base (not a branch; regen.sh fetches it). regen.sh generates again from today's specs, renames that output the same way, and does a three-way git merge onto keen. Spec changes land, and keen's own edits stay. Files keen writes by hand (README, docs, changelog, the patch list) always keep keen's version. scripts/regen/postfix.py applies keen's standing rules to code the generator adds for the first time. scripts/regen/placeholders.py gives help examples a placeholder that fits each argument (the generator puts your-token-here in every *Key argument), and check.sh fails if one slips back.

If the merge stops on a conflict, the script lists the files. Resolve them in the work folder it prints (scripts/regen/resolve.py ours|theirs <file> takes one side for a whole file), then run scripts/regen/finish.sh. Both scripts remove the work folder they made once the merge is in your checkout (a folder you name with REGEN_WORK is kept), and check.sh removes its build folder however it ends. When the branch is merged to main, move the base forward as regen.sh says.

To see what Atlassian has changed since the last refresh, without changing anything, run scripts/regen/specdiff.py. It lists the operations added, removed or changed in each spec. A weekly GitHub workflow (.github/workflows/spec-check.yml) runs the same check, opens one issue when anything differs and closes it once keen is current again, so a change is never missed.

scripts/mcp-check.py <dir with keen and keen-mcp> tests the MCP server against a live site the way an AI app uses it: it asks keen_search for ten everyday tasks in plain words, runs the tool through keen_run and compares the answer with the CLI's. It fails when the right tool is not in the top three, or when a tool ranked above it is one Atlassian has switched off. With --claude it also hands Claude Code keen-mcp as its only tools and checks it answers real questions with no failed call. It picks its test data from the site, and check.sh runs it alongside the live smoke test.

To add an Atlassian API, add one name=URL line to the end of SPECS and run the two commands above. Nothing else needs editing.

The org chart and Teamwork Graph commands come from Atlassian's GraphQL schema instead of an OpenAPI spec. scripts/regen/graphql.py reads it (no login needed), keeps a snapshot in specs/graphql.json and writes the command table; the refresh runs it, and the weekly check compares the live schema with the snapshot.

If Atlassian retires an API, the generator stops producing its command. Add it to internal/compat/compat.go so the old command and MCP tool keep their name and tell people what replaced it. Every local change is listed in .printing-press-patches.json.

Atlassian also keeps deprecated APIs in its specs, sometimes after switching them off. scripts/regen/deprecated.py lists every operation the specs mark deprecated (the refresh runs it, and check.sh fails if the list is out of date); keen labels those commands and tools, and keen_search ranks them below the alternatives. When one starts answering 410 Gone, add it to RemovedEndpoints in internal/compat/deprecated.go with what to use instead: keen then hides it, its command and tool name the replacement, and keen sync skips it.

Security

See SECURITY.md for vulnerability reporting. Keen reads API credentials from environment variables or from ~/.config/keen/auth.json. If you use the file, keep it readable only by you (chmod 600). The local SQLite database contains cached API responses and should be treated as sensitive.

Contributing

See CONTRIBUTING.md. Bug fixes welcome. Open an issue before submitting PRs for new features.

License

Apache-2.0

Built by Imogen Labs