Jira Enterprise MCP

Small MCP server for Codex that connects to enterprise Jira with a Jira personal access token.

What it does

Tests connectivity to Jira
Lists accessible Jira projects
Looks up a Jira issue by key
Looks up a Jira issue by key, including derived acceptance criteria when present in a custom field
Looks up a Jira issue by key and can return screenshot/image attachments as MCP image content, including derived acceptance criteria when present in a custom field
Fetches individual attachments and can return raw attachment bytes as base64, with image attachments also exposed as MCP image content
Inspects issue creation metadata for a project and issue type, with a fallback for tenants that do not expose createmeta
Runs JQL searches
Creates a Jira issue
Updates an existing issue
Lists issue comments
Lists or performs issue transitions
Uploads attachments to an issue
Uploads an attachment and posts a comment that references it, with optional inline image markup
Lists linked issues
Fetches and creates worklog entries
Adds a comment to an existing issue

Requirements

Node.js 18+
A Jira PAT that works against your Jira instance
Network access to your Jira base URL

Setup

Install dependencies:

npm install

Copy .env.example to .env and fill in your values:

cp .env.example .env

Export the variables before launching the MCP server, or let Codex pass them in:

export JIRA_BASE_URL=https://your-jira.example.com
export JIRA_PAT=your-token
export JIRA_DEFAULT_PROJECT=YOURPROJECT

Run locally

npm start

Recommended validation flow

Use this order when validating a new PAT against your Jira instance:

jira_test_connection
jira_list_projects
jira_get_create_meta
jira_get_issue
jira_get_issue_with_images
jira_get_attachment
jira_list_issue_comments
jira_transition_issue
jira_update_issue
jira_search
jira_create_issue
jira_add_attachment
jira_add_comment_with_attachment
jira_get_issue_links
jira_get_worklog
jira_add_worklog
jira_add_comment

This matters because enterprise Jira tenants often allow reads before creates, and issue creation may require project-specific issue types or custom fields.

Codex CLI / GUI wiring

If you are using Codex locally, point an MCP entry at this server command:

{
  "mcpServers": {
    "jira-enterprise": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira.example.com",
        "JIRA_PAT": "YOUR_PAT",
        "JIRA_DEFAULT_PROJECT": "YOURPROJECT"
      }
    }
  }
}

If you prefer the Codex CLI helper, the shape should be equivalent to:

codex mcp add jira-enterprise --env JIRA_BASE_URL=https://your-jira.example.com --env JIRA_PAT=YOUR_PAT --env JIRA_DEFAULT_PROJECT=YOURPROJECT -- node /absolute/path/to/src/index.js

The exact config location can vary by Codex app version, so use whichever local MCP configuration flow your Codex build exposes.

Notes

This server uses Authorization: Bearer <PAT>.
If your Jira instance accepts UI logins but rejects API calls, the PAT may not be enabled for your tenant or may require a different auth scheme.
If your Jira admins require custom CA certificates, you may need to trust that certificate at the OS or Node runtime level before this server can connect cleanly.
On some Jira tenants, createmeta may return 404 "Issue Does Not Exist". The MCP falls back to project issue types and workflow statuses so you can still discover valid issue types even when field-level create metadata is unavailable.

Tools

jira_test_connection
jira_list_projects
jira_get_issue
jira_get_issue_with_images
jira_get_attachment
jira_list_issue_comments
jira_transition_issue
jira_update_issue
jira_get_create_meta
jira_search
jira_create_issue
jira_add_attachment
jira_add_comment_with_attachment
jira_get_issue_links
jira_get_worklog
jira_add_worklog
jira_add_comment

Attachment content behavior

jira_get_attachment with includeContent: false returns attachment metadata only.
jira_get_attachment with includeContent: true returns raw file bytes in contentBase64 with contentEncoding: "base64".
For image attachments such as PNGs, the tool also includes MCP image preview content, but the downloadable bytes are always in contentBase64.

Jira Enterprise MCP