Codex Jira Stories MCP

Local MCP server that lets the Codex CLI query Jira Cloud and publish already-reviewed stories. It was designed to work with the local jira-stories skill: the skill writes the story; this server queries the project and creates or updates the issue.

Flow security

• Credentials are not stored in the repository: they are read from JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN.

• Write tools require confirmPublish: true.

• There is no deletion tool.

• Before publishing, use jira_preview_issue and check the result.

Related MCP server: JIRA MCP Server

Preparation

1. Copy .env.example to a safe location and export the variables in the terminal. Do not create or version a .env file with credentials.

2. Confirm that the account has Browse projects and Create issues permissions on the desired Jira project.

3. Register the server in the Codex CLI:

codex mcp add jira-stories \
  --env JIRA_BASE_URL="$JIRA_BASE_URL" \
  --env JIRA_EMAIL="$JIRA_EMAIL" \
  --env JIRA_API_TOKEN="$JIRA_API_TOKEN" \
  -- node /Users/emenezes/projetos/codex-jira-stories-mcp/src/server.mjs

Then open a new Codex session and run /mcp to confirm that jira-stories is active.

Available tools

Conversation example

Write a functional story to allow PDF report export. Query the available Jira projects, generate a preview for the AGR project, and only publish after I approve.

To publish an approved preview, explicitly ask Codex to use jira_create_issue with confirmPublish: true. The description is converted from plain text or basic Markdown to the document format accepted by Jira Cloud.

Local verification

npm test

Current limitations

This first version supports Jira Cloud via API token. For environments with mandatory SSO or a delegated authorization requirement, the next step is to replace the authentication with OAuth 2.0 on the MCP server, preserving the same tools.