Skip to main content
Glama
deenesjakoruzh
stubbedev

atlassian-mcp

by stubbedev
OverviewSchemaRelated ServersScoreDiscussions
Go
Local

atlassian-mcp

A Model Context Protocol (MCP) server for self-hosted Jira (Server / Data Center) and self-hosted Bitbucket (Server / Data Center). Exposes tools for natural-language workflows around tickets, pull requests, review threads, and git context.

Note: This server only supports self-hosted instances. Jira Cloud and Bitbucket Cloud use different APIs and are not supported.

Tools

Workflow

Tool

Description

get_dev_context

Master entry point: git state + linked Jira ticket + open PR with reviewer/blocker status and next-step hints

start_work

Start a Jira ticket: resolves it by key or free-text query (with a picker when several match), creates a local branch (feature/FOO-123-slug) off the repository default branch, fetches the project README from Bitbucket so commit/PR conventions are in context, and optionally transitions the ticket

complete_work

Close out finished work: merges the open PR and transitions the Jira ticket to Done. Refuses to merge while reviewers have not approved or a build failed (force=true overrides)

Git

Tool

Description

git_get_context

Branch, upstream state, remote URL, recent commits, working tree status, diff stat, and Jira keys in branch name. Pass fromRef/toRef for a diff between refs instead, paged via charOffset

Jira

Tool

Description

jira_search

Discover resources: issues, projects, issue_types, boards, sprints, board_overview, versions, components, fields, or users via resource param

jira_get

Full details for one issue: summary, description, status, sprint, transitions, comments, and attachment list

jira_mutate

Create, update, transition, comment (commentAction: add / update / delete), upload local files as attachments, link, add to sprint, log work, change issue type, set any custom field by name (create.customFields / update.customFields), or manage a fix version (version.action: create / update / release / archive / delete) — several in one call. Markdown in any text field is converted to Jira wiki markup

Bitbucket

Tool

Description

bitbucket_search

Discover resources: pull_requests (default), repos, branches, or users via resource param; mine=true for your inbox, narrowed with role=author / reviewer / participant

bitbucket_get_pr

Full PR details: metadata, commits, comments, blockers, build status, optional diff, and any attachments referenced from the description or comments

bitbucket_mutate

Create/update a PR, or perform lifecycle actions: approve, unapprove, needs_work, merge, decline. Reviewer names are verified against Bitbucket, and an update that would drop existing reviewers needs update.replaceReviewers=true. create.attachments / update.attachments upload local files (screenshots, logs) to the repo and reference them from the description

bitbucket_comment

Add, update, or delete a PR comment; for code changes use suggestion so Bitbucket shows Apply suggestion. Enforced here: one reply per thread, no new top-level comment on your own PR (asAuthor=true to override), #123 references rewritten as links. pending=true posts an unpublished draft-review comment. attachments uploads local files and references them from the comment

bitbucket_get_file

Raw file content at a branch, tag, or commit — or pass prId to read the PR source branch. Every response names the path and ref it came from, and pages via maxChars/charOffset

bitbucket_pr_tasks

Manage PR tasks (checklist items): list, create, resolve, reopen, delete

Shared

Tool

Description

get_attachment

Fetch an attachment by ID from Jira (source=jira, IDs from jira_get) or Bitbucket (source=bitbucket, IDs from bitbucket_get_pr). Images, videos, animated images (GIF/APNG/animated WebP), audio, and PDFs are decoded inline so the model can see/hear them; text/JSON inline. Oversized or non-renderable attachments are auto-saved to a temp file and the path is returned. saveTo=/absolute/path streams the original to disk

Resources

URI

Description

dev-context://current

The same live report as get_dev_context — branch state, linked Jira tickets, open PR — as an MCP resource. Re-read it for fresh state instead of spending another tool call. The repo is resolved per read from the caller's session, so the static URI serves whatever workspace the client is in

Natural language examples

  • "what am I working on?" → get_dev_context

  • "make a branch for FOO-123" → start_work

  • "ship this / merge and close the ticket" → complete_work

  • "show my PRs waiting for review" → bitbucket_search with mine=true

  • "list open PRs for this repo from feature/ABC-123" → bitbucket_search with fromBranch

  • "give me a full overview of PR 42" → bitbucket_get_pr

  • "open a PR from my current branch to master" → bitbucket_mutate with create

  • "approve / merge / decline PR 42" → bitbucket_mutate with action

  • "reply to comment 123 on PR 42" → bitbucket_comment with commentId=123

  • "resolve this blocker on PR 42" → bitbucket_comment with action=update, severity=BLOCKER, state=RESOLVED

  • "list PR checklist tasks" → bitbucket_pr_tasks with action=list

  • "find bugs assigned to me in PAY project" → jira_search with mine=true, issueType=Bug

  • "what's in the current sprint?" → jira_search with resource=board_overview

  • "move FOO-123 to In Progress" → jira_mutate with transitionName="In Progress"

  • "log 2h on FOO-123" → jira_mutate with worklog

  • "create version 9.1.0 in PAY" → jira_mutate with version.action=create, version.projectKey=PAY, version.name=9.1.0

  • "list releases for PAY" → jira_search with resource=versions, project=PAY

  • "release version 12345" → jira_mutate with version.action=release, version.id=12345

  • "set fix version 9.1.0 on FOO-123" → jira_mutate with update.fixVersion=9.1.0

  • "create a task under epic FOO-100" → jira_mutate with create.issueType=Task, create.parent=FOO-100 (auto-detects Epic and sets Epic Link)

  • "move FOO-123 under epic FOO-100" → jira_mutate with update.epicLink=FOO-100

  • "create an epic" → jira_mutate with create.issueType=Epic (Epic Name defaults to the summary)

  • "set story points to 5" → jira_mutate with update.customFields={"Story Points": 5} — values are plain (option label, username, date, array of labels); the server wraps them per the field schema

  • "what can I set on this ticket / on an Epic?" → jira_search resource=fields with issueKey=FOO-123 (edit screen) or project=FOO+issueType=Epic (create screen): required and optional fields, value shapes, allowed values

Related MCP server: Bitbucket Server MCP

What the server enforces

These are guarantees in the code, not advice in a tool description — a client cannot get them wrong, and they need no prompting:

  • Arguments are validated before a call runs. Enum values and required fields are checked against each tool's schema, with case and -/_ differences normalised. An unknown action/resource is an error, never a silent fallback to some default branch of the handler.

  • Names are resolved before anything is written. Jira assignee/reporter, components and fix versions, and Bitbucket reviewers are checked first; a bad one comes back with the valid options instead of an opaque 400.

  • Markdown is converted to Jira wiki markup on every Jira write (comments, descriptions, worklogs). Text that is already wiki markup is left alone.

  • PR comment hygiene: one reply per thread per author, no duplicate of a comment you already posted, no new top-level comment on a PR you authored (asAuthor=true to override), no tasks via severity, no emoji, and bare #123 references are rewritten as links to that comment.

  • Inline comments anchor to what was reviewed. Reading a PR records the commit pair for that session; inline comments bind to it and are remapped onto current head when the branch has moved, so a comment never lands on unrelated code.

  • Reviewers are never dropped by accident — an update that would remove one needs update.replaceReviewers=true.

  • complete_work will not merge while reviewers have not approved or a build on the PR head has failed, unless force=true.

  • Truncated output always says how to continue, naming the argument that fetches the rest. bitbucket_get_file also states the path and ref it read, so reading the wrong branch is visible rather than silent.

  • Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are published for every tool, so hosts can gate confirmation on metadata.

Setup

1. Create a config file

Create ~/.atlassian-mcp.json:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

The $schema field is optional but enables editor autocomplete and validation.

  • projectKey means a project code:

    • Jira example: PAY in ticket PAY-123

    • Bitbucket example: project ENG in repo path ENG/payments-service

  • You can also use ergonomic aliases:

    • Jira: project (alias of projectKey)

    • Bitbucket: project and repo (aliases of projectKey and repoSlug)

  • For Bitbucket tools, projectKey and repoSlug are usually auto-detected from your local origin remote.

  • bitbucket_mutate with create auto-detects fromBranch from your current branch and returns the existing open PR if one already exists for that branch. Other Bitbucket tools auto-target that PR when prId is omitted.

  • Jira project-scoped calls accept projectKey and work best when provided.

  • If projectKey is omitted for Jira issue creation/type lookup, the server tries to infer it from your current branch ticket key, falls back to auto-select when only one project is visible, and otherwise returns a numbered project list to pick from.

Alternatively, use environment variables (or a .env file in this directory):

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

Config is resolved in this order: --config <path> CLI arg → ATLASSIAN_MCP_CONFIG env var → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json (default ~/.config/atlassian-mcp/config.json) → .atlassian-mcp.json in cwd → environment variables. A leading ~ in the first two is expanded by the server, so a client that spawns it without a shell still resolves the path. Within a file, per-field: a value in the config file wins, environment variables fill the gaps.

2. Connect to your AI tool

No cloning or building required — just point your tool at npx @stubbedev/atlassian-mcp@latest and it will install and run automatically.

CLI-driven clients need one line:

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest       # Claude Code
codex mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest        # Codex CLI / IDE / app
code --add-mcp '{"name":"atlassian","command":"npx","args":["-y","@stubbedev/atlassian-mcp@latest"]}'   # VS Code

Desktop apps: Claude Desktop installs a one-click .mcpb bundle — no Node, no JSON. Everything else takes a config file; see below.

Note: --prefer-online can break MCP startup in some clients. Keep the command simple and use the update steps below when you want to refresh.

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Claude Desktop

One-click (recommended). Grab the .mcpb bundle for your platform from the latest release — atlassian-mcp_darwin_arm64.mcpb (Apple Silicon), atlassian-mcp_darwin_amd64.mcpb (Intel Mac), atlassian-mcp_windows_amd64.mcpb — then double-click it, drag it onto the Claude Desktop window, or use Settings → Extensions → Advanced settings → Install Extension…. The install dialog asks for Jira/Bitbucket URL and token (tokens are stored by Claude Desktop, not in a file) plus Repository, the working tree the git and PR tools default to. Leaving URL/token blank reuses an existing ~/.atlassian-mcp.json.

The bundle carries the binary, so there is no Node, no npx, no PATH to fix and no JSON to edit. MCP Bundles are a Claude Desktop feature today; other clients use the config files below.

Manual config. Claude Desktop is a GUI app: it launches the server with a minimal PATH, no shell, and / as the working directory. So command must be an absolute path (a bare npx fails with spawn npx ENOENT), a .env file or relative --config path never resolves, and nothing expands ~ for you — the server expands a leading ~ in --config / ATLASSIAN_MCP_CONFIG itself, but a client that inserts ~ anywhere else will not. Config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "atlassian": {
      "command": "/absolute/path/to/atlassian-mcp",
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_ACCESS_TOKEN": "your-jira-personal-access-token",
        "BITBUCKET_URL": "https://bitbucket.example.com",
        "BITBUCKET_ACCESS_TOKEN": "your-bitbucket-personal-access-token",
        "ATLASSIAN_MCP_REPO_ROOT": "/Users/you/code/my-repo"
      }
    }
  }
}

To keep npx, set command to the absolute path of your launcher (which npx, e.g. /opt/homebrew/bin/npx) with "args": ["-y", "@stubbedev/atlassian-mcp@latest"].

ATLASSIAN_MCP_REPO_ROOT is what makes get_dev_context, git_get_context, start_work, complete_work and Bitbucket repo auto-detection usable here: a desktop app has no workspace, so it advertises no MCP roots and there is no useful cwd to fall back to. Comma-separate several worktrees (first git repo wins); a per-call repoPath still overrides it.

On Windows, Git is frequently absent from a GUI app's PATH. The server probes the usual install locations before giving up; set ATLASSIAN_MCP_GIT_PATH if yours lives elsewhere.

Server stderr is logged to ~/Library/Logs/Claude/mcp-server-atlassian.log (macOS) or %APPDATA%\Claude\logs\mcp-server-atlassian.log (Windows) — read that first when a connection fails.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-only):

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

Add to opencode.json in your project root (or ~/.config/opencode/opencode.json for global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"],
      "environment": { "ATLASSIAN_MCP_REPO_ROOT": "/home/you/code/my-repo" }
    }
  }
}

environment also accepts the JIRA_* / BITBUCKET_* variables if you would rather not keep a config file. Set "type": "remote" with "url" and "headers" to point at a shared HTTP server instead.

Codex (CLI, IDE extension, app)

One command — it writes the config for all three:

codex mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest

Or edit ~/.codex/config.toml directly (.codex/config.toml in a trusted project for a project-scoped server). Note the TOML table name is mcp_servers, with an underscore:

[mcp_servers.atlassian]
command = "npx"
args = ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]

# Optional — instead of a config file, and to pin the repo for the git/PR tools:
[mcp_servers.atlassian.env]
JIRA_URL = "https://jira.example.com"
JIRA_ACCESS_TOKEN = "…"
ATLASSIAN_MCP_REPO_ROOT = "/home/you/code/my-repo"

Codex picks the transport from the keys present: command means stdio, url means streamable HTTP. To share one HTTP server:

[mcp_servers.atlassian]
url = "http://127.0.0.1:7337/mcp"
bearer_token_env_var = "ATLASSIAN_MCP_HTTP_TOKEN"

VS Code / GitHub Copilot

code --add-mcp '{"name":"atlassian","command":"npx","args":["-y","@stubbedev/atlassian-mcp@latest"]}'

Or commit .vscode/mcp.json with a servers object of the same shape to share it with the repo.

Any other MCP-compatible tool

Most clients accept the Claude Desktop shape — an mcpServers object keyed by name, with command, args and env:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest"],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_ACCESS_TOKEN": "…",
        "BITBUCKET_URL": "https://bitbucket.example.com",
        "BITBUCKET_ACCESS_TOKEN": "…",
        "ATLASSIAN_MCP_REPO_ROOT": "/home/you/code/my-repo"
      }
    }
  }
}

LM Studio uses exactly that shape in its own mcp.json (edit it from the app's plugin panel); Cherry Studio, Witsy, Jan and 5ire have in-app MCP dialogs with the same fields.

Goose is the exception — its ~/.config/goose/config.yaml uses extensions: with cmd rather than command:

extensions:
  atlassian:
    enabled: true
    type: stdio
    cmd: npx
    args: ["-y", "@stubbedev/atlassian-mcp@latest"]
    envs:
      ATLASSIAN_MCP_REPO_ROOT: /home/you/code/my-repo

Every GUI client brings the caveats from the Claude Desktop section: absolute command path, no usable cwd, no MCP roots — so set ATLASSIAN_MCP_REPO_ROOT.

ChatGPT (desktop / web) — not supported

ChatGPT connectors accept remote HTTPS MCP servers only (streamable HTTP or SSE, with OAuth or no auth); it cannot spawn a local stdio server. This server's --http mode speaks the right protocol, but making it work would mean exposing an endpoint that reaches your self-hosted Jira/Bitbucket to OpenAI's servers, and ChatGPT offers no place for the static bearer token this server uses. Use a client from the list above.

Updating existing installs

If your MCP client is already configured and you want the newest package version:

npx clear-npx-cache

Then restart your MCP client.

Install without npm

The server is a single static Go binary. The npx path above downloads the prebuilt binary for your platform on first run; these alternatives skip Node entirely — as does the .mcpb bundle for Claude Desktop, and the per-platform binaries attached to every release:

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

Then point your MCP client's command at the resulting atlassian-mcp binary instead of npx. On these Node-free paths (go install, Nix, a release binary or the .mcpb bundle) ffmpeg/ffprobe must be available on PATH for video and animated-image attachments (or set ATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATH); the npm wrapper bundles them automatically. Everything else — still images, PDF text, JSON/text — is pure Go and needs nothing extra.

Running as an HTTP server (shared / behind a proxy)

By default the server speaks MCP over stdio (one process per client, launched by your editor). It can instead run as a long-lived Streamable HTTP server that many clients share — useful behind a reverse proxy:

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

  • Single endpoint POST /mcp (JSON-RPC) plus an optional GET /mcp SSE stream that carries server→client requests (roots/list, elicitation). The server is stateful: initialize mints a session and returns an Mcp-Session-Id header, which the client must echo on every subsequent request and on the SSE stream. Requests with a missing/unknown/expired session id get HTTP 404 so the client re-initializes (standard MCP-client behaviour). Each connected client/worktree is an isolated session; per-session state (cached roots, PR review anchors) is dropped once the session ends.

  • Auth: on a loopback bind no token is needed. Binding a non-loopback address requires ATLASSIAN_MCP_HTTP_TOKEN (sent by clients as Authorization: Bearer …); the server refuses to start otherwise. Terminate TLS at your proxy.

  • GET /healthz is an unauthenticated liveness probe (returns ok) for proxies/load balancers.

Repo context comes from the client, not the server's working directory. Tools that need a repo (git_get_context, get_dev_context, start_work, complete_work, and Bitbucket project/repo auto-detection) resolve it in this order: an explicit repoPath argument → a root pinned via request header (see below) → ATLASSIAN_MCP_REPO_ROOT (comma-separated for several worktrees — the only workspace signal a GUI desktop client can give) → the client's MCP workspace roots (the server asks via roots/list, caches per session, and refreshes on notifications/roots/list_changed) → the process cwd (stdio only). So one shared HTTP server handles many worktrees: each client's own workspace drives its calls. When a session exposes several roots (multiple worktrees), a tool with no repoPath uses the first git-repo root; pass repoPath (an absolute path, or a worktree name/basename that matches one of the roots) to target a specific worktree. For Bitbucket, passing projectKey+repoSlug explicitly skips repo detection entirely. The repos must be reachable on the server's host (the git tools run git locally).

Pinning the root via a request header (HTTP). A reverse proxy or harness that already knows the working tree can hand it to the server directly, skipping the roots/list round-trip (and working even when the client never advertised the roots capability). Send a file:// URI or absolute path (comma-separated for multiple; first git repo wins):

X-Repo-Root: /srv/myrepo
X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

Accepted header names, in precedence order: X-Repo-Root, X-Mcp-Roots, X-Mcp-Root, Mcp-Roots, Mcp-Root. A header value is authoritative — it takes precedence over roots/list and survives list_changed.

Protocol note: MCP revision 2026-07-28 (SEP-2322/2575) forbids server-initiated JSON-RPC requests, so roots/list is unavailable on that revision — the server says so explicitly instead of hanging. On 2026-07-28 clients, a root header (or an explicit repoPath / projectKey+repoSlug) is the only way to give the server repo context.

Client config for an already-running HTTP server (Claude Code example):

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

Attachment decoding pipeline

The get_attachment tool decodes binary attachments into model-readable content before returning them:

Input

What gets returned

How

Static images (PNG/JPEG/WebP/BMP/TIFF/GIF/SVG…)

Resized image content blocks

native Go (imaging, long edge ≤ maxDimension, default 1568; EXIF auto-orient; PNG for alpha, else JPEG)

Animated images (GIF/APNG/animated WebP)

N sampled frames as image content blocks

ffmpeg + native Go re-encode (default 6 frames @ 768 px)

Video (mp4/webm/mov/…)

N sampled frames as image content blocks

ffmpeg/ffprobe. Uniform or scene-change sampling. Re-call with start, end, frames, mode, sceneThreshold to zoom in

Audio (mp3/wav/ogg/…)

MCP audio content block

passthrough

PDFs

Extracted text — or rasterized pages if text is empty (scanned PDFs)

native Go text extraction (ledongthuc/pdf); rasterization shells to pdftoppm/mutool if present, else the original is saved to disk

Text-like (json/xml/yaml/…)

Text content block

passthrough

Everything else (or oversized)

Auto-saved to a temp file; path is returned

os.TempDir() with atlmcp- prefix

Auto-saved files are periodically pruned by TTL and total-size quota — see Environment overrides below.

External tools (optional)

Image and PDF-text decoding are pure Go and need nothing extra. The two pipelines that have no pure-Go implementation shell out to external binaries:

  • ffmpeg + ffprobe — video and animated-image frame sampling. The npm wrapper bundles ffmpeg-static / ffprobe-static and injects their paths, so the npx install path is zero-config. On every Node-free path (go install, Nix, release binary, .mcpb bundle), install ffmpeg (it provides ffprobe) or set the env vars below.

  • pdftoppm (poppler) or mutool (MuPDF) — only needed to rasterize scanned PDFs that have no extractable text. If neither is on PATH, such PDFs are saved to disk instead.

Environment overrides

Variable

Purpose

Default

ATLASSIAN_MCP_HTTP

Run as a Streamable HTTP server instead of stdio. 1/true → 127.0.0.1:7337; or set an explicit host:port. Same as --http.

unset (stdio)

ATLASSIAN_MCP_HTTP_TOKEN

Bearer token for HTTP mode. Optional on loopback binds; required on non-loopback binds.

unset

ATLASSIAN_MCP_REPO_ROOT

Default workspace root(s) for the git/PR tools, comma-separated. file:// URIs, absolute paths, ~/… and Windows drive paths all work. Needed by clients that expose no MCP roots (desktop apps). Overridden by a repoPath argument or a root header.

unset

ATLASSIAN_MCP_GIT_PATH

Path to the git executable. Only needed when git is off the host app's PATH; the server already probes the usual install locations.

git on PATH

ATLASSIAN_MCP_FFMPEG_PATH

Path to ffmpeg binary.

npm: bundled ffmpeg-static; otherwise ffmpeg on PATH

ATLASSIAN_MCP_FFPROBE_PATH

Path to ffprobe binary.

npm: bundled ffprobe-static; otherwise ffprobe on PATH

ATLASSIAN_MCP_TMP_TTL_DAYS

Auto-saved attachments older than this are pruned.

7

ATLASSIAN_MCP_TMP_MAX_BYTES

Total-size quota for auto-saved attachments in os.tmpdir(). When exceeded, oldest are evicted.

1073741824 (1 GB)

Releases (Maintainers)

This package is published to npm as @stubbedev/atlassian-mcp.

Use semantic versioning for releases. Breaking tool-surface changes should bump the minor version while <1.0.0 (for example 0.0.x -> 0.1.0).

On a pushed v* tag, .github/workflows/publish.yml cross-compiles the Go binary for 14 OS/arch targets, packs six of them into .mcpb bundles for one-click desktop install (packaging/mcpb/pack.sh, macOS/Windows/Linux × amd64/arm64), attaches everything to a GitHub release, and publishes the npm wrapper (which downloads the matching binary on install). just bundle builds a bundle for the host platform locally.

Release flow (just drives it; it refuses to run on a dirty tree):

just release-preview       # show the next patch/minor/major versions
just release-patch         # or release-minor / release-major

just release-<level> bumps the version in package.json, re-syncs the Nix vendorHash (just sync-flake), runs the gates (just check), commits release: vX.Y.Z, tags, and pushes both the branch and the tag. The tag push triggers publish.yml.

package.json is the single source of truth for the version: the binary embeds it via go:embed (no -ldflags) and flake.nix reads it, so one bump moves everything. The equivalent npm scripts (npm run release:patch / :minor / :major) still work.

  • The workflow is configured for npm Trusted Publisher (OIDC), so no NPM_TOKEN secret is required

Required npm setup (one-time):

  • In npm package settings, add this GitHub repo/workflow as a Trusted Publisher

Creating Personal Access Tokens

Jira Server / Data Center

Personal Access Tokens are supported from Jira 8.14 onwards.

  1. Log in to your Jira instance.

  2. Click your profile avatar in the top-right corner and select Profile.

  3. In the left sidebar, click Personal Access Tokens.

  4. Click Create token.

  5. Give the token a name (e.g. atlassian-mcp) and optionally set an expiry date.

  6. Click Create and copy the token — it will only be shown once.

Paste the token as the token value under jira in your config file.

If your Jira version is older than 8.14, you can use HTTP Basic Auth instead — but this server only supports Bearer token (PAT) authentication.

Bitbucket Server / Data Center

Personal Access Tokens are supported from Bitbucket Server 5.5 onwards.

  1. Log in to your Bitbucket instance.

  2. Click your profile avatar in the top-right corner and select Manage account.

  3. In the left sidebar, under Security, click Personal access tokens.

  4. Click Create a token.

  5. Give the token a name (e.g. atlassian-mcp).

  6. Set the permissions:

    • Projects: Read

    • Repositories: Read + Write (Write is needed to create pull requests and add comments)

  7. Optionally set an expiry date.

  8. Click Create and copy the token — it will only be shown once.

Paste the token as the token value under bitbucket in your config file.

Development

The server is a single Go module at the repo root (no src/ tree).

Tasks live in the justfile and mirror the CI gates, so a green just check predicts green CI:

just            # list tasks
just check      # vet + test + build (what ci.yml runs)
just fmt        # gofmt -w .
just sync-flake # recompute the Nix vendorHash after a dependency change

# Or the raw commands
go build -o atlassian-mcp .
./atlassian-mcp --config /path/to/config.json
go vet ./... && go test ./...

# Quick release smoke check (build + tools/list validation; CI also does a full stdio handshake)
npm run smoke

Tool schemas live in tools.json (embedded into the binary) and the MCP protocol layer is the official modelcontextprotocol/go-sdk; the Go files at the repo root hold the tool logic.

Available Tools

10 tools
get_dev_contextA

Master entry point for "what am I working on / what's the status", and before any review or coding task. Returns: git branch + upstream state, Jira ticket overview (status, transitions, sprint, comments), open PR with reviewer approvals, and actionable next-step hints (create PR, merge, address blockers).

ParametersJSON Schema
NameRequiredDescriptionDefault
repoPathNoLocal path to the git repo (defaults to cwd)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses all returned data elements (git branch, Jira ticket overview, open PR, next-step hints), which is good transparency. It does not describe side effects or auth needs, but the tool appears read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is two sentences: first defines purpose, second lists returns. It is concise with no wasted words, though some structure (e.g., bullet points) could improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the return values. The tool has one optional parameter and simple behavior; the description covers what the agent needs to know for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The parameter 'repoPath' is described in the schema as 'Local path to the git repo (defaults to cwd)'. The description does not add further meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it is the master entry point for status and before tasks. It lists specific returned items (git branch, Jira ticket, PR, next steps) and distinguishes from sibling tools like git_get_context and jira_get by being a higher-level aggregator.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use before any review or coding task, and for getting status. This provides clear context. While it doesn't specify when not to use, the sibling tools imply alternatives for more granular needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

git_get_contextA

Start here for any coding or review task: current branch, upstream ahead/behind, remote URL, recent commits, working tree status, diff stat summary, and Jira keys detected in the branch name. Pass includeDiff=true to also include the full uncommitted diff.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoPathNoPath to the git repository (defaults to cwd)
commitLimitNoNumber of recent commits to show (default 10)
includeDiffNoInclude full uncommitted diff (default false)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description lists outputs (branch, commits, status, diff, Jira keys) and the effect of includeDiff. However, does not state that the tool is read-only or specify any prerequisites (e.g., must be in a git repo).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. First sentence front-loads all context items; second sentence adds optional flag. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all key aspects: what is returned, optional diff, and Jira integration. Lacks details on output format and error conditions, but sufficient for a gathering tool without output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description adds context for includeDiff ('full uncommitted diff') but does not significantly enhance understanding beyond schema descriptions. Falls to baseline due to high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it provides a comprehensive set of git and Jira context items for coding/review tasks, distinguishing it from sibling tools like git_get_diff and get_dev_context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Start here', indicating primary usage for coding/review tasks. Mentions optional includeDiff parameter. Does not explicitly exclude alternatives but context signals and sibling names imply differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

git_get_diffA

Get a diff between two git refs or commits. Use when you need to compare a feature branch to main, inspect a specific commit range, or review changes between two refs. For large diffs, increase maxChars or use charOffset to page through them.

ParametersJSON Schema
NameRequiredDescriptionDefault
repoPathNoPath to the git repository (defaults to cwd)
fromRefNoBase ref or commit
toRefNoTarget ref or commit (requires fromRef)
maxCharsNoMax characters to return (default 8000). Increase for large diffs.
charOffsetNoSkip this many characters from the start (for paging large diffs)

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry behavioral transparency. It mentions paging via charOffset and maxChars, but does not describe the output format (e.g., unified diff), handling of errors, or limits. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second provides usage scenarios. Very concise with no wasted words. Could be slightly more structured, but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 well-documented parameters, no output schema, and no annotations, the description explains the core functionality and provides paging guidance. It misses details about diff output format but is fairly complete for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter. The description reinforces usage of maxChars and charOffset for large diffs, adding marginal value beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get a diff between two git refs or commits' and lists specific use cases like comparing a feature branch to main. It distinguishes itself from siblings like git_get_context and JIRA tools by focusing on git diffs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool ('when you need to compare a feature branch to main...') and provides guidance for large diffs. It does not include when-not-to-use or alternative tools, but the sibling names provide context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_commentA

Add, update, or delete a comment on a Jira issue. action defaults to "add". Can only edit/delete your own comments. Use Jira wiki markup (Atlassian renderer syntax), not GitHub/CommonMark markdown.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoOperation (default: add)
issueKeyYesJira issue key, e.g. FOO-123
commentIdNoComment ID (required for update/delete)
bodyNoComment text. Use Jira wiki markup (Atlassian renderer syntax), not GitHub/CommonMark markdown. Required for add/update.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavioral aspects: it restricts editing/deleting to own comments and specifies markup format. It lacks some details like rate limits or response format, but for a CRUD tool, it is reasonably transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each carrying essential information. No filler or redundancy. It is front-loaded with the core purpose and proceeds to key constraints. Exceptionally concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no output schema, no annotations), the description covers the main functional aspects: operations, own-comment limitation, and markup. It could include an example or mention return values, but it is adequately complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% coverage with descriptions for all parameters. The description adds value by stating the default action and the own-comment restriction, which are not in the schema. It thus enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action: Add, update, or delete a comment on a Jira issue. It clearly identifies the resource (Jira issue comment) and the specific operations, distinguishing it from sibling tools like jira_get or jira_mutate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies that action defaults to 'add', can only edit/delete own comments, and must use Jira wiki markup. This provides clear context for using the tool, though it does not explicitly mention when not to use it or name specific alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_getA

Full details for one Jira issue: summary, description, status, assignee, sprint, available transitions, recent comments, and a list of attachments (filename, size, mime type, attachment ID). To view an attachment's contents (e.g. an image), call jira_get_attachment with the attachment ID surfaced here.

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyYesJira issue key, e.g. FOO-123
includeCommentsNoInclude comments (default true)
commentsMaxResultsNoMax comments (default 10)
commentsStartAtNoComment pagination offset (default 0)
includeTransitionsNoInclude available transitions (default true)
includeSprintNoInclude sprint data (default true)
fullDescriptionNoReturn the full description even when long (default false — descriptions over ~2000 chars are truncated to save context)

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral disclosure burden. It explains the effect of the fullDescription parameter (truncation) and mentions 'recent comments', but does not specify recency limits, pagination for attachments, authentication needs, or error behavior. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, no redundant words. Every sentence provides essential information about what the tool returns and how to use related tools. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description lists the key return fields (summary, description, status, etc.), which is sufficient for an agent to understand the output. It also references a sibling tool for next steps. Some details (e.g., comment structure) are omitted, but overall it is complete enough for a read operation with 7 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the fullDescription truncation behavior and explicitly linking jira_get_attachment to the attachment ID surfaced by this tool, which is not in the schema. This enriches parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves full details for one Jira issue, listing specific fields (summary, description, status, assignee, sprint, transitions, comments, attachments). It distinguishes from sibling tools by mentioning jira_get_attachment for attachment contents, and implicitly from jira_search (multiple issues) and jira_mutate (updates).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use and an alternative: 'To view an attachment's contents... call jira_get_attachment'. It does not cover when to use this vs. jira_search for listing issues, but the alternative guidance is clear and valuable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_get_attachmentA

Fetch a Jira attachment by ID and return its contents inline. Images are auto-resized + re-encoded; text/JSON/XML return as text; videos and animated images (GIF/APNG/animated WebP) are decoded with ffmpeg into sampled frames (re-call with start/end/frames or mode=scenes to refine); audio returns as an audio block; PDFs return extracted text. Oversized/non-renderable files are saved to a temp file and the path returned. Use jira_get first to discover attachment IDs.

ParametersJSON Schema
NameRequiredDescriptionDefault
attachmentIdYesNumeric attachment ID from jira_get output
saveToNoOptional absolute path to save the original (un-resized) file to disk instead of returning inline
maxDimensionNoMax long-edge size in pixels for inline images (default 1568 for images, 768 for video frames).
qualityNoJPEG quality for re-encoded inline images (1-100, default 85 for images, 65 for video frames). Ignored for images with alpha (encoded as PNG).
framesNoVideo/animated-image only: number of frames to sample (default 6, range 1-60). Higher = more detail + more context.
startNoVideo/animated-image only: start of sample window in seconds (default 0). Use with end/frames to zoom into a moment of interest after a coarse first pass.
endNoVideo/animated-image only: end of sample window in seconds (default full duration). Must be greater than start.
modeNoVideo/animated-image only: "uniform" samples N frames evenly (default); "scenes" uses ffmpeg scene-change detection, better for screencasts/narrative content.
sceneThresholdNoVideo/animated-image only: scene-change sensitivity in 0-1 (default 0.3). Only used when mode=scenes. Lower = more frames, higher = fewer.

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description fully discloses behaviors: auto-resizing, re-encoding, video decoding with ffmpeg, text/PDF/audio handling, and fallback to temp file for oversized content. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the main action, but could benefit from clearer structuring. All sentences contribute useful information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all parameter details, return types, and media-specific behaviors. Missing error handling cases (e.g., invalid attachment ID), but overall complete given the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, baseline is 3. Description adds value by specifying parameter usage contexts (e.g., 'Video/animated-image only') and providing defaults, ranges, and refinements like 'start/end/frames or mode=scenes'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch a Jira attachment by ID and return its contents inline', specifying the verb, resource, and outcome. It distinguishes from sibling tools by mentioning use with jira_get to discover IDs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to use jira_get first and explains handling of various media types, but lacks explicit when-not-to-use scenarios or detailed alternatives for optional parameters like saveTo vs inline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_mutateA

Create/update a ticket, transition status, assign, comment, link issues, or log work — bundles create/update/transition/comment/link/worklog in one call. Use Jira wiki markup (Atlassian renderer syntax), not GitHub/CommonMark markdown.

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyNoExisting issue key to mutate (optional if create is provided)
createNo
updateNo
sprintIdNoSprint ID to add the issue into (optional)
removeFromSprintNoMove the issue to the backlog (remove from any sprint)
transitionIdNoTransition ID (optional if transitionName provided)
transitionNameNoTransition name, e.g. "In Progress" (optional if transitionId provided)
commentNoComment to add after other mutations (optional). Use Jira wiki markup (Atlassian renderer syntax), not GitHub/CommonMark markdown.
linkNoCreate an issue link, e.g. "FOO-123 blocks BAR-456"
worklogNoLog time spent on this issue

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the markup syntax requirement (Jira wiki vs. markdown), which is a behavioral trait. However, it does not mention error handling, ordering of multiple operations, authentication needs, or whether operations are atomic. The definition is incomplete for a complex mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first lists all operations concisely, the second provides the critical markup warning. Every sentence adds value without redundancy. It is front-loaded and easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (10 parameters, nested objects, no output schema), the description provides a high-level overview and the crucial markup constraint. It does not explain return values or operation ordering, but the rich schema compensates partially. Lacks some behavioral context but is fairly complete for an initial understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high (80%), so baseline is 3. The description adds value by specifying the markup format requirement for description and comment fields, which is not in the schema. It also clarifies the bundling aspect. This goes beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool bundles multiple mutation operations (create, update, transition, comment, link, worklog) in one call. It uses specific verbs and identifies the resource (Jira ticket). This distinguishes it from siblings like jira_comment, which is only for comments, and jira_get (read-only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when any combination of the listed mutations is needed. It emphasizes bundling (one call) which guides efficient usage. However, it does not explicitly contrast with siblings like jira_comment for standalone commenting, nor mention when not to use (e.g., read-only scenarios).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_versionA

Manage Jira fix versions (releases): create, update, release, archive, delete. action defaults to "create". For create pass projectKey + name. For update/release/archive/delete pass id (look it up via jira_search resource=versions). "release" sets released=true and defaults releaseDate to today. Once a version exists you can set it on tickets via jira_mutate update.fixVersion.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoOperation (default: create)
projectKeyNoJira project code (required for create when not auto-resolvable)
projectNoAlias for projectKey
idNoVersion id (required for update/release/archive/delete; look up via jira_search resource=versions)
nameNoVersion name, e.g. "9.1.0" (required for create; optional rename for update)
descriptionNoVersion description (optional)
startDateNoStart date in YYYY-MM-DD (optional)
releaseDateNoRelease date in YYYY-MM-DD (optional; defaults to today on action=release)
releasedNoReleased flag (optional; action=release forces true)
archivedNoArchived flag (optional; action=archive forces true)

TDQS

A4.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses action defaults, that 'release' sets released=true and defaults releaseDate to today. However, it does not mention side effects of delete/archive or any destructive behavior beyond the action names.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose and actions, no wasted words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 actions, 10 params, and no output schema, the description covers all actions, required params per action, links to sibling tools for lookup and usage, and provides a post-creation hint. Very complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds significant meaning: clarifies which parameters are required per action (projectKey+name for create, id for others), and explains defaults/forced values (released=true on release, archived=true on archive, releaseDate defaults to today). This goes well beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it manages Jira fix versions with five specific actions, and references sibling tools jira_search and jira_mutate for lookup and ticket assignment, distinguishing itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use each action: create requires projectKey+name; other actions require id from jira_search. Also notes that after creation, jira_mutate can set the version on tickets. Provides clear context and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_workA

Start working on a Jira ticket end-to-end: resolves the ticket (by key or free-text search with a picker when multiple match), creates a local branch with an auto-generated name, fetches the project README from Bitbucket so you have commit/PR conventions in context, and prints a next-steps summary. If issueKey is omitted, provide query for free-text search.

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyNoJira issue key, e.g. FOO-123 (provide this OR query)
queryNoFree-text search when issueKey is unknown — shows a picker if multiple tickets match
repoPathNoLocal repo path (defaults to cwd)
baseBranchNoBranch to base off (default: master)
branchNameNoOverride the generated branch name
transitionNameNoJira transition to apply, e.g. "In Progress" (optional)
pushNoPush branch to remote after creation (default false)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behaviors: ticket resolution, branch creation, README fetch, summary printing, and optional push/transition. Without annotations, it carries the burden, and it covers most major actions, though omits details like error handling or default behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences that front-load the core action and key conditional guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main workflow steps and optional parameters, but could be more detailed about error cases or the exact Jira transitions applied. Given the lack of output schema and annotations, it provides a reasonable overview for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds minor value by explaining the relationship between issueKey and query, but otherwise does not significantly enhance parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to start working on a Jira ticket end-to-end, including resolving the ticket, creating a local branch, fetching a README, and printing a summary. It distinguishes from sibling tools by combining multiple actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use the issueKey vs query parameters, but does not explicitly exclude use cases for sibling tools like jira_mutate or git_get_context. However, the tool's workflow-oriented purpose is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.4.2
    • Changedjira_get1 field changed
      • addedInput schema / properties / fullDescription
        Added value: +{
+  "default": false,
+  "description": "Return the full description even when long (default false — descriptions over ~2000 chars are truncated to save context)",
+  "type": "boolean"
+}
  2. 1 tool updatev0.4.1
    • Changedjira_get_attachment7 fields changed
      • addedInput schema / properties / end
        Added value: +{
+  "description": "Video/animated-image only: end of sample window in seconds (default full duration). Must be greater than start.",
+  "type": "number"
+}
      • addedInput schema / properties / frames
        Added value: +{
+  "description": "Video/animated-image only: number of frames to sample (default 6, range 1-60). Higher = more detail + more context.",
+  "type": "number"
+}
      • changedInput schema / properties / maxDimension / description
        Previous value: -"Max long-edge size in pixels for inline images (default 1568). Larger images are downscaled with sharp."New value: +"Max long-edge size in pixels for inline images (default 1568 for images, 768 for video frames)."
      • addedInput schema / properties / mode
        Added value: +{
+  "description": "Video/animated-image only: \"uniform\" samples N frames evenly (default); \"scenes\" uses ffmpeg scene-change detection, better for screencasts/narrative content.",
+  "enum": [
+    "uniform",
+    "scenes"
+  ],
+  "type": "string"
+}
      • changedInput schema / properties / quality / description
        Previous value: -"JPEG quality for re-encoded inline images (1-100, default 85). Ignored for images with alpha (encoded as PNG)."New value: +"JPEG quality for re-encoded inline images (1-100, default 85 for images, 65 for video frames). Ignored for images with alpha (encoded as PNG)."
      • addedInput schema / properties / sceneThreshold
        Added value: +{
+  "description": "Video/animated-image only: scene-change sensitivity in 0-1 (default 0.3). Only used when mode=scenes. Lower = more frames, higher = fewer.",
+  "type": "number"
+}
      • addedInput schema / properties / start
        Added value: +{
+  "description": "Video/animated-image only: start of sample window in seconds (default 0). Use with end/frames to zoom into a moment of interest after a coarse first pass.",
+  "type": "number"
+}
  3. 10 tool updatesv0.3.10
    • First observedget_dev_context
    • First observedgit_get_context
    • First observedgit_get_diff
    • First observedjira_comment
    • First observedjira_get
    • First observedjira_get_attachment
    • First observedjira_mutate
    • First observedjira_search
    • First observedjira_version
    • First observedstart_work
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: git context, diffs, Jira CRUD, search, comments, attachments, version management, and a workflow starter. No overlap in functionality.

Naming Consistency4/5

Most tools use a verb_noun pattern with a prefix (git_, jira_), but get_dev_context and start_work break the pattern. jira_mutate is also slightly vague. Overall consistent.

Tool Count5/5

10 tools is well-scoped for a server integrating Git and Jira, providing comprehensive coverage without being overwhelming.

Completeness3/5

Covers Jira thoroughly but lacks tools for Git operations like creating PRs or pushing branches beyond start_work. Missing Jira issue deletion. Some gaps in workflow.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/stubbedev/atlassian-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server