gojira-mcp

Atlassian Cloud admin MCP server. Wraps the platform-administration surface that the official Atlassian Rovo MCP deliberately omits — project/scheme management, custom field admin, Jira automation CRUD, Assets (Insight) CMDB, JSM request type / SLA / queue config, Confluence space lifecycle, and the org-admin APIs at admin.atlassian.com.

Designed to run alongside the official Atlassian MCP in a single client session, not as a replacement.

Status

Quickstart

1. Generate an encryption key

npm install
npm run generate-key
# copy the base64 string into TOKEN_ENCRYPTION_KEY in your .env

2. Configure

cp .env.example .env
$EDITOR .env

Required at minimum:

• ATLASSIAN_OAUTH_CLIENT_ID, ATLASSIAN_OAUTH_CLIENT_SECRET from the Atlassian developer console

• ATLASSIAN_OAUTH_SCOPES — space-separated Atlassian OAuth scopes (must include offline_access)

• TOKEN_ENCRYPTION_KEY — output of npm run generate-key

• ALLOWED_ORIGINS — * for development, explicit origins for production

• MCP_SERVER_URL — public URL of this server (callback must match)

See docs/deployment/environment-variables.md for the full list with defaults and gotchas.

3. Run

Locally (dev):

docker run --rm -p 6379:6379 redis:7-alpine    # in one terminal
npm run dev                                     # in another

Docker (production):

docker compose up -d
# or with a Caddy TLS overlay:
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

The server listens on MCP_PORT (default 8081) with:

• GET /health — unauthenticated liveness + Redis ping

• GET /.well-known/oauth-authorization-server — OAuth metadata

• POST /register — RFC 7591 client registration

• GET /authorize — OAuth 2.1 authorize entry

• POST /token — token + refresh endpoint

• POST /revoke — token revocation

• GET /oauth/atlassian-callback — upstream callback

• POST|GET|DELETE /mcp — bearer-protected MCP transport

4. Verify

curl -fsS "http://localhost:8081/health" | jq

Then point an MCP client (Claude Desktop, VS Code chat, Claude Code, Cursor) at https://<host>/mcp. The client will discover the OAuth endpoints, walk the consent flow with you against Atlassian, and start calling tools.

For first-time setup of the JSM/Assets tools, call gojira.bindApiToken once to attach a per-user Atlassian API token.

Deployment patterns

One image, many configs. Each deployment shape below is a different .env file pointing at the same gojira-mcp:latest image. Run as many side-by-side instances as you need — different hostnames, ports, audit channels, and tool surfaces, all isolated from each other.

The total tool count for each pattern is shown next to the pattern name. Lower is better for model selection accuracy — see docs/tools/overview.md.

Pattern 1 — Default safe (admin sandbox) · 145 tools

Daily admin work, no destructive project deletion, no org-admin path. Good starting point for a single team's instance.

Active groups: utility, all read_* (10 groups), all write_* except none excluded, plus the safe project surface — minus delete_projects and admin_org.

ATLASSIAN_OAUTH_CLIENT_ID=...
ATLASSIAN_OAUTH_CLIENT_SECRET=...
ATLASSIAN_OAUTH_SCOPES=offline_access read:me read:account read:jira-work write:jira-work manage:jira-project manage:jira-configuration read:servicedesk-request write:servicedesk-request manage:servicedesk-customer
ATLASSIAN_PINNED_CLOUD_ID=<prod-cloud-id>
TOKEN_ENCRYPTION_KEY=<base64>
ALLOWED_ORIGINS=*
MCP_SERVER_URL=https://gojira.example.com
GOJIRA_DISABLED_GROUPS=delete_projects,admin_org

Pattern 2 — Read-only audit · 81 tools

Every write_*, delete_projects, and admin_org group disabled. Useful for compliance reviewers, incident investigators, or any flow that must not mutate Atlassian state.

Active groups: utility + all 10 read_* groups.

GOJIRA_DISABLED_GROUPS=write_jsm_admin,write_assets,write_automation,write_customfields,write_projects,write_schemes,write_workflows,write_confluence_admin,delete_projects,write_agile,write_filters_dashboards,admin_org

(Same auth/secret/cloud config as Pattern 1.)

Pattern 3 — JSM/Assets specialist · 63 tools

Service-desk operators who don't need automation rules, custom fields, schemes, workflows, agile, or filters/dashboards.

Active groups: utility, read_jsm_admin, write_jsm_admin, read_assets, write_assets.

ATLASSIAN_OAUTH_SCOPES=offline_access read:me read:account read:jira-work write:jira-work read:servicedesk-request write:servicedesk-request manage:servicedesk-customer
GOJIRA_DISABLED_GROUPS=read_automation,write_automation,read_customfields,write_customfields,read_projects,write_projects,read_schemes,write_schemes,read_workflows,write_workflows,read_confluence_admin,write_confluence_admin,delete_projects,read_agile,write_agile,read_filters_dashboards,write_filters_dashboards,admin_org

Pattern 4 — Schemes/workflows admin · 62 tools

Configuration-change instance for Jira admins. Excludes JSM, Assets, Confluence, agile, and filters/dashboards.

Active groups: utility, read_automation, write_automation, read_customfields, write_customfields, read_projects, write_projects, delete_projects, read_schemes, write_schemes, read_workflows, write_workflows.

ATLASSIAN_OAUTH_SCOPES=offline_access read:me read:account read:jira-work write:jira-work manage:jira-project manage:jira-configuration
GOJIRA_DISABLED_GROUPS=read_jsm_admin,write_jsm_admin,read_assets,write_assets,read_confluence_admin,write_confluence_admin,read_agile,write_agile,read_filters_dashboards,write_filters_dashboards,admin_org

Pattern 5 — Org-admin (separate instance, separate host) · 31 tools

Run on its own hostname/port. Only admin_org and utility tools register. Audit goes to a separate channel.

Active groups: utility, admin_org.

ATLASSIAN_OAUTH_SCOPES=offline_access read:me read:account
ATLASSIAN_PINNED_CLOUD_ID=<prod-cloud-id>
GOJIRA_ENABLE_ORG_ADMIN=true
GOJIRA_ORG_ADMIN_TOKEN=<admin.atlassian.com api token>
GOJIRA_ORG_ID=<your-org-id>
GOJIRA_ORG_ADMIN_AUDIT_LOG_TARGET=file:/var/log/gojira/org-admin.log
GOJIRA_DISABLED_GROUPS=read_jsm_admin,write_jsm_admin,read_assets,write_assets,read_automation,write_automation,read_customfields,write_customfields,read_projects,write_projects,read_schemes,write_schemes,read_workflows,write_workflows,read_confluence_admin,write_confluence_admin,delete_projects,read_agile,write_agile,read_filters_dashboards,write_filters_dashboards

Caller verification still requires the calling user to be an org admin on the Atlassian side; non-admins get INSUFFICIENT_PERMISSIONS even on this instance.

Pattern 6 — Multi-tenant (prod + sandbox side-by-side) · 145 tools each

Two instances, same image, two compose stacks, two hostnames:

gojira.prod.example.com    →  ATLASSIAN_PINNED_CLOUD_ID=<prod cloudId>
gojira.sandbox.example.com →  ATLASSIAN_PINNED_CLOUD_ID=<sandbox cloudId>

A user with grants on both cloudIds can connect both as separate connectors in their MCP client; site pinning ensures each instance only ever talks to its own tenant.

Pattern 7 — Local development · 145 tools

ATLASSIAN_OAUTH_CLIENT_ID=...
ATLASSIAN_OAUTH_CLIENT_SECRET=...
ATLASSIAN_OAUTH_SCOPES=offline_access read:me read:account read:jira-work write:jira-work manage:jira-project manage:jira-configuration read:servicedesk-request write:servicedesk-request manage:servicedesk-customer
TOKEN_ENCRYPTION_KEY=<base64>
ALLOWED_ORIGINS=*
MCP_SERVER_URL=http://localhost:8081
GOJIRA_DISABLED_GROUPS=delete_projects,admin_org
LOG_LEVEL=debug
NODE_ENV=development
# no PINNED_CLOUD_ID — use the user's primary cloudId

Documentation map

Architecture

• Overview

• Auth bridge

• Session lifecycle

• Rate limiting

• Operation journal

• Commit-positive consent

• Site pinning

• Refresh-token rotation

• Error model

OAuth

• Flow

• OAuth scope handling

• API-token side-channel

• Org-admin token

Tools

• Overview

• Permission groups

• Utility tools

• Daily admin tools

• Schemes, workflows, Confluence admin

• Agile and views

• Org admin (gated)

• Full catalog (auto-generated)

Deployment

• Environment variables

• Docker Compose

• Caddy TLS overlay

• Secrets management

• Deploy procedure

• Health checks

Security

• Threat model

• Error codes

• Audit trail

• Refresh-token reuse detection

Operations

• Journal and revert

• Incident response

• Backup and recovery

Development

• Repo layout

• Testing

• Adding a tool

Reference

• Redis schema

• HTTP routes

Design properties

The features below are the things this server does that a naïve admin MCP typically gets wrong:

1. Per-user delegation. Every upstream Atlassian call is attributable to a real human; no service-account proxying.

2. End-to-end identity binding. Tools cannot accept a caller/requester field from the client; identity is derived from the bearer.

3. Encrypted-at-rest credentials. AES-256-GCM, unique IV per write, tampered blobs auto-purge.

4. Distributed refresh lock with compare-and-delete. No thundering herd at token expiry; no accidental unlock by a stale holder.

5. Atomic one-time-use for state, codes, and refresh artifacts (GETDEL).

6. OAuth error pass-through to MCP client's redirect_uri — never a hung client on JSON 500.

7. Allowlist-based query construction — no string concatenation of user input into upstream queries.

8. Fail-open rate limiting, fail-closed auth. Availability for non-security failures; never bypass identity.

9. Health endpoint outside the auth boundary — observability without privilege.

10. Token redaction in logs as defense in depth.

11. Rotating MCP refresh tokens with reuse detection. Family-tracked; presenting a previously-rotated RT while siblings are alive triggers full-family revocation + a REFRESH_TOKEN_REUSE audit event.

12. Operation journal with prior-state snapshots and revert. Every destructive admin write captures before state; revertible operations can be undone by replaying the inverse mutation as a new journaled op.

13. Operator-controlled tool surface, least-privilege by default. Permission groups + the admin_org gate are the runtime knobs. GOJIRA_DISABLED_GROUPS filters the registered surface at session creation and again at dispatch. No client-side scope grammar to mismanage.

14. Site pinning at deploy time. ATLASSIAN_PINNED_CLOUD_ID refuses any tool invocation whose target cloudId differs from the pinned value.

15. Commit-positive consent on destructive writes. Tools without commit: true return a JSON Patch dry-run; forgotten flag fails closed.

16. Rate-limit-header-aware throttling. X-RateLimit-NearLimit triggers proactive extra-token deduction; X-RateLimit-Reset soft-caps the bucket until the future window.

17. Three-tier auth strategy with explicit isolation of the org-admin path.

License

Internal / unlicensed. See package.json.