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.

Permission groups (legend)

Each value in GOJIRA_ENABLED_GROUPS names one of these 23 groups. The allowlist is required at startup and validated against this list; unknown names fail loudly. See docs/tools/permission-groups.md for the per-tool breakdown and docs/tools/catalog.md for the full auto-generated catalog.

Notes:

• delete_projects is split out from write_projects so an operator can grant create/archive without granting deletion.
• admin_org needs both allowlisting and GOJIRA_ENABLE_ORG_ADMIN=true; see docs/oauth/org-admin-token.md.
• Auth column reflects how the tool reaches Atlassian: oauth = per-user OAuth bearer; api_token = per-user side-channel token via gojira.bindApiToken; org_admin = the single global GOJIRA_ORG_ADMIN_TOKEN; mixed = some tools in the group don't need any credential (e.g. gojira.health).

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 10 read_*, all 9 write_*, plus write_projects (but not delete_projects or 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_ENABLED_GROUPS=utility,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,read_agile,write_agile,read_filters_dashboards,write_filters_dashboards

Pattern 2 — Read-only audit · 81 tools

Only utility + every read_* group enabled. Useful for compliance reviewers, incident investigators, or any flow that must not mutate Atlassian state.

Active groups: utility + all 10 read_* groups.

GOJIRA_ENABLED_GROUPS=utility,read_jsm_admin,read_assets,read_automation,read_customfields,read_projects,read_schemes,read_workflows,read_confluence_admin,read_agile,read_filters_dashboards

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

Pattern 3 — JSM/Assets specialist · 63 tools

Service-desk operators who only need JSM and Assets.

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_ENABLED_GROUPS=utility,read_jsm_admin,write_jsm_admin,read_assets,write_assets

Pattern 4 — Schemes/workflows admin · 62 tools

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

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_ENABLED_GROUPS=utility,read_automation,write_automation,read_customfields,write_customfields,read_projects,write_projects,delete_projects,read_schemes,write_schemes,read_workflows,write_workflows

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_ENABLED_GROUPS=utility,admin_org

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>

Both use the Pattern-1 GOJIRA_ENABLED_GROUPS. 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_ENABLED_GROUPS=utility,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,read_agile,write_agile,read_filters_dashboards,write_filters_dashboards
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_ENABLED_GROUPS is an explicit allowlist (no implicit default) that 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.