Small MCP server for Codex that connects to enterprise Jira with a Jira personal access token.
- 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
- Node.js 18+
- A Jira PAT that works against your Jira instance
- Network access to your Jira base URL
- Install dependencies:
npm install- Copy
.env.exampleto.envand fill in your values if you want a local template file:
cp .env.example .env- Export the variables before launching the MCP server, or let your MCP host pass them in:
export JIRA_BASE_URL=https://your-jira.example.com
export JIRA_PAT=your-token
export JIRA_DEFAULT_PROJECT=YOURPROJECT
export JIRA_REQUEST_TIMEOUT_MS=30000
export JIRA_MAX_ATTACHMENT_BYTES=26214400npm startNote: this server reads JIRA_BASE_URL, JIRA_PAT, and JIRA_DEFAULT_PROJECT from process.env. It does not load .env automatically, so .env.example is a template, not a runtime loader.
src/index.jsstarts the stdio transport only.src/server.jsbuilds the MCP server and wires tool listing/call handlers.src/jira-client.jsowns Jira HTTP requests, auth headers, timeouts, attachment downloads, and uploads.src/tools/*-tools.jsco-locates each feature area's MCP tool schemas with its handlers.src/tools/registry.jscombines feature modules into the MCP tool list and dispatch table.src/config.js,src/validation.js,src/jira-formatters.js, andsrc/mcp-content.jskeep shared config, validation, serialization, and MCP response helpers isolated.
Use this order when validating a new PAT against your Jira instance:
jira_test_connectionjira_list_projectsjira_get_create_metajira_get_issuejira_get_issue_with_imagesjira_get_attachmentjira_list_issue_commentsjira_transition_issuejira_update_issuejira_searchjira_create_issuejira_add_attachmentjira_add_comment_with_attachmentjira_get_issue_linksjira_get_worklogjira_add_worklogjira_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.
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.jsThe exact config location can vary by Codex app version, so use whichever local MCP configuration flow your Codex build exposes.
For Claude clients that support local MCP servers, use the equivalent mcpServers entry and pass the same environment variables:
{
"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 your Claude app exposes an MCP configuration file or settings UI, add the server there. The important part is that Claude launches node /absolute/path/to/src/index.js with those three env vars present.
- This server uses
Authorization: Bearer <PAT>. JIRA_REQUEST_TIMEOUT_MSandJIRA_MAX_ATTACHMENT_BYTESare optional safety limits. Defaults are 30 seconds and 25 MiB.- 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,
createmetamay return404 "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.
jira_test_connectionjira_list_projectsjira_get_issuejira_get_issue_with_imagesjira_get_attachmentjira_list_issue_commentsjira_transition_issuejira_update_issuejira_get_create_metajira_searchjira_create_issuejira_add_attachmentjira_add_comment_with_attachmentjira_get_issue_linksjira_get_worklogjira_add_worklogjira_add_comment
jira_get_attachmentwithincludeContent: falsereturns attachment metadata only.jira_get_attachmentwithincludeContent: truereturns raw file bytes incontentBase64withcontentEncoding: "base64".- For image attachments such as PNGs, the tool also includes MCP image preview content, but the downloadable bytes are always in
contentBase64.