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

1. Install dependencies:

npm install

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

cp .env.example .env

3. 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:

1. jira_test_connection
2. jira_list_projects
3. jira_get_create_meta
4. jira_get_issue
5. jira_get_issue_with_images
6. jira_get_attachment
7. jira_list_issue_comments
8. jira_transition_issue
9. jira_update_issue
10. jira_search
11. jira_create_issue
12. jira_add_attachment
13. jira_add_comment_with_attachment
14. jira_get_issue_links
15. jira_get_worklog
16. jira_add_worklog
17. 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.