Jira — Cloud & Data Center

Overview

c3_jira is a single MCP tool that talks to Jira Cloud (REST v3, email + API token, ADF-aware) and Jira Data Center / Server (REST v2, Personal Access Token, plain-text bodies) behind one action-dispatched interface. Claude Code (and you, via the project dashboard) reads and writes issues without a browser context-switch.

What you get

Quick start

Three commands to connect a Jira site and pin a working project.

c3 jira login \
  --url https://yoursite.atlassian.net

c3 jira set-default --project PROJ

c3 jira status

Self-hosted Data Center needs the deployment spelled out:

c3 jira login --url https://jira.example.com --deployment data_center

Anything you want reusable across every project (a personal Cloud account) belongs in the global config:

c3 jira login --global --url https://yoursite.atlassian.net

First call from Claude Code

# Connection + account probe, then your open work
c3_jira(action='status')
c3_jira(action='my_issues')

# Raw JQL
c3_jira(action='search', jql='project = PROJ AND status != Done ORDER BY updated DESC')

# Full detail on one issue
c3_jira(action='get_issue', issue='PROJ-123')

Authentication & security

API tokens / PATs

Cloud uses your email plus an API token from id.atlassian.com → Security → API tokens (Basic auth over HTTPS). Data Center uses a username plus a Personal Access Token from your profile's Personal Access Tokens page (Bearer auth). Neither surface scopes the token independently of the account's own Jira permissions — whatever that user can do in the browser, c3_jira can do through the API. Use a dedicated service account with only the project access you intend to grant the agent, especially before enabling delete_issue.

Where the token lives

Deployment inference

_jira_deployment_for checks the host: *.atlassian.net or *.jira.com infers cloud automatically. Any other host needs --deployment data_center on the command line — c3 jira login refuses with an explicit error rather than guessing.

TLS verification

Default: verify_tls = true. --insecure on c3 jira login disables verification (and allows http://); --ca-bundle <path> points at a custom CA bundle for a self-signed enterprise certificate without disabling verification entirely.

Named accounts, multiple sites

Every login is stored under a name (--name work, --name internal), defaulting to the URL's host label when omitted. Pass account=<name> on any c3_jira call to use a non-default account for that one call; switch the default with c3 jira use --name <name>.

Reusable across projects

c3 jira login --global writes the account to ~/.c3/config.json. Resolution mirrors Bitbucket: the project's jira section wins when its default_account resolves against its own accounts registry; otherwise C3 falls back to the home config. The section is taken wholesale from exactly one file — project fields are never merged over a home-registered account. That's a deliberate security invariant: a repository's committed config must not be able to override the credential-bound base_url, username, deployment, or TLS settings of an account it did not register. Tokens are additionally keyed by (base_url, username) in the keyring, so a rewritten base_url can never retrieve the original server's token.

Action reference

The MCP tool dispatches by action. Twenty-five actions, grouped below by capability. project falls back to the account's default_project when the action takes one and omits it.

Read & discovery

Issue writes

Sprints, worklogs, attachments

The full parameter reference also lives on the tool card.

CLI commands

Five subcommands cover account lifecycle and project defaults. Run any with --help for full flags.

Every subcommand also takes a positional project_path (default: current directory) — the C3 project whose .c3/config.json to write, unless --global redirects login to ~/.c3.

Project dashboard tab

Endpoints powering the tab live in cli/server.py under /api/jira/*: status, issues/my, board, search, issue/<key> (GET and POST for create), issue/<key>/transition, issue/<key>/comment, issue/<key>/assign, and activity.

Audit trail — edit ledger integration

State changes on the Jira side aren't in your local working tree, so they're still appended to the C3 edit ledger. The path is virtual:

jira://<issue-or-project-key>

Logged actions — identifiers only, bodies and arbitrary field contents are never logged:

Read it back with c3_edits(action='history', file='jira://PROJ-123'), or via the activity log's jira_action events (also what powers the dashboard's Activity view).

.c3/config.json — jira section

Default shape (created on first c3 jira login):

{
  "jira": {
    "default_account": "yoursite",
    "accounts": {
      "yoursite": {
        "base_url": "https://yoursite.atlassian.net",
        "username": "alice@example.com",
        "deployment": "cloud",
        "default_project": "PROJ",
        "verify_tls": true,
        "ca_bundle": ""
      }
    }
  }
}

Example workflows

Triage your open work

c3_jira(action='my_issues', status_category='indeterminate')
c3_jira(action='get_issue', issue='PROJ-123')

File a bug — pre-validated against metadata

# See what the project + issue type actually require
c3_jira(action='get_create_metadata', project='PROJ', issue_type='Bug')

# Create — missing required fields come back instead of a guess
c3_jira(action='create_issue', project='PROJ', issue_type='Bug',
        summary='Login redirect loops on Safari',
        description='Repro steps in thread')

Put an issue under an epic, then link two issues

c3_jira(action='update_issue', issue='PROJ-124', parent='PROJ-42')
c3_jira(action='link_issues', issue='PROJ-1', link_type='blocks', target='PROJ-2')

A field gets rejected on create

# [jira:api-error] ... It is not on the appropriate screen
# Create without the field, then set it separately:
c3_jira(action='update_issue', issue='PROJ-124',
        fields='{"customfield_10014": "value"}')

Sprint flow: board → sprint → move an issue

c3_jira(action='list_boards')
c3_jira(action='list_sprints', board_id=7, sprint_state='active')
c3_jira(action='move_to_sprint', issue='PROJ-1,PROJ-2', sprint_id=42)

Log time and attach evidence

c3_jira(action='add_worklog', issue='PROJ-1', time_spent='2h 30m', body='Pairing on the redirect fix')
c3_jira(action='attach_file', issue='PROJ-1', file_path='logs/repro.log')

Move an issue through its workflow

c3_jira(action='list_transitions', issue='PROJ-123')
c3_jira(action='transition', issue='PROJ-123', transition='In Progress')
c3_jira(action='comment', issue='PROJ-123', body='Deployed to staging')

Troubleshooting

Where to look

• Activity log: project dashboard → Jira tab → Activity, plus .c3/activity_log.jsonl for raw events tagged jira_action.
• Edit ledger: c3_edits(action='history', file='jira://<issue-or-project-key>') for every mutation.
• Tool calls: c3_session(action='log') entries record every c3_jira dispatch with its action name and (sanitized) args.