Jira云AI集成工具

jira2ai

Jira Cloud integrations for AI clients and local automation. Requires Python 3.13+.

Choose a product

• jira2mcp — the published MCP server. Use it with any MCP client that supports a stdio server; Claude Code is one example.
• jira2cli — the published flat Jira Cloud CLI. Run it with uvx jira2cli; local checkout commands are for contributors.

Both are Jira Cloud only. They do not support Jira Server or Data Center, and do not provide dedicated issue assignment, issue delete/archive, sprint/board/epic, or admin-configuration operations.

Start with MCP

Install uv and configure your MCP client to launch the published server over stdio:

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["jira2mcp"]
    }
  }
}

For Claude Code, the equivalent command is:

claude mcp add jira -- uvx jira2mcp

See the MCP guide for client configuration, the complete jira_* tool inventory, and examples.

Use the CLI

Install uv on Python 3.13 or later, configure credentials below, then run the published CLI:

uvx jira2cli --help
uvx jira2cli auth-status
uvx jira2cli read PROJ-123 --fields summary,status --json

Authentication and safety

Set these environment variables for either product:

export JIRA_URL="https://yourcompany.atlassian.net"
export JIRA_USER="you@company.com"
export JIRA_API_TOKEN="your-api-token"

Create an API token in your Atlassian account. Both products also accept an explicit JSON credentials file through --credentials-file; that explicit file is used instead of environment credentials. There is no default credentials-file path and no JIRA_CREDENTIALS_FILE environment variable.

Keep API tokens out of source control, logs, prompts, and shared client configuration. Jira access is limited by the configured account's Jira permissions. Read metadata and the current issue state before writes, then confirm the exact fields, IDs, transition, or destructive action.

What you can do

The products support authentication checks, issue reads and JQL search, complete issue changelog history, projects, create/edit field metadata, a one-page field catalog, comments, transitions, saved filters, issue links, attachments, and worklogs. changelogs retrieves every Jira history page and can filter timestamps and exact field IDs locally; it can optionally page the retained events. changelogs-by-ids uses Jira's distinct known-ID request and can filter exact field IDs. Descriptions and comments accept Markdown. Plain CLI issue reads can render selected rich-text fields, while JSON and MCP structured issue reads preserve Jira's raw field data.

Markdown images from attachments

For an existing issue, high-level Markdown writes accept ![alt](attachment-content-url) for an image already attached to that issue. Get the ordinary URL from the existing content field in the JSON/raw attachment-upload result, then use it in an issue edit, comment add/update, or worklog comment add/update. On issue edit, this applies to the explicit description option and environment or supported custom textarea field strings supplied through the existing fields input; it does not convert plain fields or raw Jira API inputs.

Issue creation cannot embed its own new attachment. Create the issue, upload the image to its returned key, then edit the complete rich-text field; edits replace whole field values rather than appending.

Managed attachment images are sized transparently during ordinary Markdown writes: their intrinsic dimensions are used with a centered 100% media container at the document root and in Markdown lists. External URLs are never fetched and remain external media without managed sizing. If safe dimensions cannot be acquired from an attached Jira image, the write fails before Jira receives a mutation.

For local development or contributions, see CONTRIBUTING.md. Contributors working from a repository checkout use uv run --locked --package jira2cli jira2cli ... after workspace setup. The optional Pi CLI skill is a source-checkout template for agents using jira2cli; UVX runs the CLI but does not install or auto-discover the skill.

License

MIT