jira-mcp
Model Context Protocol (MCP) server for Jira Cloud. Lets you search, create, update, transition, assign, delete, comment, and log work on Jira issues — directly from any MCP-compatible AI client.
Power your agent
Instal dari penerbit. Bukan endpoint PlugMCP.
URL remote atau perintah di mesin Anda? Perbedaan kedua cara instal
Jalankan di PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
BukaDari penerbit
Model Context Protocol (MCP) server for Jira Cloud. Lets you search, create, update, transition, assign, delete, comment, and log work on Jira issues — directly from any MCP-compatible AI client.
Model Context Protocol (MCP) server for Jira Cloud. Search, create, update, transition, assign, and manage Jira issues directly from Claude Desktop, Cursor, OpenCode, Windsurf, and any MCP-compatible AI client.
scratch imagejira-mcp supports two authentication methods. Basic Auth is the default and the only method that works with no extra setup. OAuth 2.0 requires an Atlassian OAuth app that you own.
Traditional email + API token authentication via environment variables. Works on any Jira Cloud site, needs no Atlassian admin approval, and is the simplest path.
Create or verify your Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
export JIRA_URL=https://yourcompany.atlassian.net
export [email protected]
export JIRA_API_TOKEN=your-api-token
Browser-based login with automatic token refresh, so no manual token creation or
rotation. It routes API calls through api.atlassian.com/ex/jira/{cloudId} and
stores tokens in ~/.config/jira-mcp/token.json with 0600 permissions.
Important: OAuth only works with an Atlassian OAuth 2.0 (3LO) app that is authorized for your site. Release binaries embed the publisher's own app, and Atlassian rejects it for any other site with "We couldn't identify the app requesting access". To use OAuth you must register your own app.
http://127.0.0.1:<port>/callback. jira-mcp binds a
random local port for each login; any port on 127.0.0.1 is accepted.read:jira-work, write:jira-work, and read:jira-user.export JIRA_OAUTH_CLIENT_ID=your-client-id
export JIRA_OAUTH_CLIENT_SECRET=your-client-secret
# The site URL is optional — it is only a hint. Pass it with --url or via
# JIRA_URL. Login works without it; Atlassian resolves the site for you.
jira-mcp auth --url https://yourcompany.atlassian.net
# Check token status
jira-mcp auth --status
# Logout and clear cached tokens
jira-mcp auth --logout
Credentials are resolved in this order: JIRA_OAUTH_CLIENT_ID /
JIRA_OAUTH_CLIENT_SECRET, then the values embedded in the binary at build
time. Set the variables whenever you want to use your own app.
Note: If
JIRA_API_TOKENis present, Basic Auth takes precedence and OAuth is not used at all.
If the browser shows "We couldn't identify the app requesting access", the app is not authorized for the site: check the app's distribution settings, or fall back to Basic Auth.
brew tap lucasvidela94/tap
brew install jira-mcp
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash
The installer can optionally configure your MCP client automatically. When run in a terminal it asks which client you want to set up, then collects the Jira site URL, your email, and an API token (Basic Auth). OAuth is not configured by the installer: an OAuth app has to be created by you in the Atlassian developer console and the browser login has to be run once afterwards.
Which MCP client do you want to configure? [opencode/claude/cursor/windsurf/none] (default: opencode):
Jira URL (e.g. https://yourcompany.atlassian.net): https://yourcompany.atlassian.net
Jira username/email: [email protected]
Jira API token:
Will write jira-mcp configuration for opencode at /home/you/.config/opencode/opencode.json
Jira URL: https://yourcompany.atlassian.net
Username: [email protected]
API token: <hidden>
Proceed? [Y/n] y
Create or verify your Jira API token at: https://id.atlassian.com/manage-profile/security/api-tokens
Skip the wizard, or pass the answers as flags:
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash -s -- --no-configure
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash -s -- \
--client opencode \
--jira-url https://yourcompany.atlassian.net \
--jira-username [email protected] \
--jira-api-token your-api-token \
--yes
Run bash install.sh --help for the full flag list (--method, --dir,
--version, --sudo, --insecure, --client, --jira-url,
--jira-username, --jira-api-token, --configure, --no-configure,
--yes, --inspect).
To use OAuth instead, see OAuth 2.0 (bring your own app)
and set the two JIRA_OAUTH_* variables in the generated config instead of the
Basic Auth ones.
Build the image locally:
docker build -t jira-mcp .
The image is built without embedded OAuth credentials, so OAuth needs your own app credentials at runtime:
docker run \
-e JIRA_OAUTH_CLIENT_ID=your-client-id \
-e JIRA_OAUTH_CLIENT_SECRET=your-client-secret \
-v ~/.config/jira-mcp:/root/.config/jira-mcp \
jira-mcp
Note: Run
jira-mcp authon your host machine first to generate the token file. The callback listens on127.0.0.1inside the container, so complete the browser login on the host before starting or restarting the container.
Basic Auth mode: Pass all credentials as environment variables:
docker run -e JIRA_URL=https://yourcompany.atlassian.net \
-e [email protected] \
-e JIRA_API_TOKEN=your-api-token \
jira-mcp
To use the HTTP/SSE transport inside a container:
docker run -p 8080:8080 \
-e JIRA_URL=https://yourcompany.atlassian.net \
-e [email protected] \
-e JIRA_API_TOKEN=your-api-token \
jira-mcp --transport http --port 8080
The published image is available from GitHub Container Registry:
docker pull ghcr.io/lucasvidela94/jira-mcp:latest
irm https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.ps1 | iex
The PowerShell installer supports the same optional auto-configuration when run interactively (Basic Auth only). Save the script first to pass the values as parameters:
irm https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.ps1 -OutFile install.ps1
.\install.ps1 -Configure -Client opencode -JiraUrl https://yourcompany.atlassian.net -JiraUsername [email protected] -JiraApiToken your-api-token -Yes
To use OAuth instead, see OAuth 2.0 (bring your own app)
and set the two JIRA_OAUTH_* variables in the generated config.
go install github.com/lucasvidela94/jira-mcp@latest
This installs the binary only; you will still need to configure your MCP client manually.
Because jira-mcp is a background MCP server, your MCP client does not update it automatically. Use the same channel you used to install it:
After updating, restart your MCP client so it reloads the new binary. Verify the version with:
jira-mcp --version
You can also update the binary directly from the CLI:
jira-mcp update
This checks GitHub releases, downloads the latest asset for your platform, verifies the checksum, and replaces the running binary. After it finishes, restart your MCP client.
If you prefer to inspect the script instead of piping it directly to your shell:
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh -o install.sh
# Review the file, then run it:
bash install.sh
Or use the built-in inspect flag:
curl -fsSL https://raw.githubusercontent.com/lucasvidela94/jira-mcp/master/scripts/install.sh | bash -s -- --inspect
Requires your own Atlassian OAuth 2.0 (3LO) app; see OAuth 2.0 (bring your own app).
The two JIRA_OAUTH_* variables are optional: when unset, release binaries fall
back to the credentials embedded at build time, which only work for the
publisher's own site.
Destructive write tools — jira_create_issue, jira_create_child_issue, and jira_delete_issue — require explicit user confirmation before they run.
When the MCP client supports elicitation, the server prompts the user interactively and executes only on accept.
When the client does not support elicitation, the tools accept a confirm parameter: pass confirm=true to authorize the action. Without it, the server refuses to run (fails closed) rather than executing without consent.
Default is on. Set JIRA_MCP_CONFIRM=off (or false, 0, no) to disable the guardrail.
All three variables are required.
After installing, configure your MCP client. Basic Auth users need
JIRA_URL, JIRA_USERNAME, and JIRA_API_TOKEN. OAuth users need their own
app credentials (JIRA_OAUTH_CLIENT_ID, JIRA_OAUTH_CLIENT_SECRET) and must run
jira-mcp auth once; JIRA_URL is optional there.
OAuth:
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_OAUTH_CLIENT_ID": "your-client-id",
"JIRA_OAUTH_CLIENT_SECRET": "your-client-secret",
"JIRA_URL": "https://yourcompany.atlassian.net"
}
}
}
}
Basic Auth:
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "[email protected]",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
OAuth:
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_OAUTH_CLIENT_ID": "your-client-id",
"JIRA_OAUTH_CLIENT_SECRET": "your-client-secret",
"JIRA_URL": "https://yourcompany.atlassian.net"
}
}
}
}
Basic Auth:
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "[email protected]",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
OAuth:
{
"mcp": {
"jira": {
"type": "local",
"command": ["jira-mcp"],
"environment": {
"JIRA_OAUTH_CLIENT_ID": "your-client-id",
"JIRA_OAUTH_CLIENT_SECRET": "your-client-secret",
"JIRA_URL": "https://yourcompany.atlassian.net"
}
}
}
}
Basic Auth:
{
"mcp": {
"jira": {
"type": "local",
"command": ["jira-mcp"],
"environment": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "[email protected]",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
OAuth:
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_OAUTH_CLIENT_ID": "your-client-id",
"JIRA_OAUTH_CLIENT_SECRET": "your-client-secret",
"JIRA_URL": "https://yourcompany.atlassian.net"
}
}
}
}
Basic Auth:
{
"mcpServers": {
"jira": {
"command": "jira-mcp",
"env": {
"JIRA_URL": "https://yourcompany.atlassian.net",
"JIRA_USERNAME": "[email protected]",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}
The jira_create_issue, jira_update_issue, and jira_create_child_issue tools accept a description that is either a plain string or a pre-built ADF document object. The jira_add_comment tool accepts a body with the same contract.
A plain string is converted to Atlassian Document Format (ADF) with the following rules:
#, ##, and ### at the start of a line produce level-1/2/3 headings.- item or * item produce a bullet list (consecutive items are grouped).- [ ] item or - [x] item produce a checkbox list ([x] marks the item done).**text** renders bold inline text.A pre-built ADF object (e.g. {"type":"doc","version":1,"content":[...]}) is embedded verbatim.
The optional fields object accepts custom Jira fields, for example:
parent: {"key":"PROJ-1"}labels: ["tag"]Set the assignee with the separate jira_assign_issue tool, or via fields as {"assignee":{"accountId":"..."}}.
Note:
jira_create_issuereturns only{id, key, self}(fields arenull). Usejira_get_issueto verify the resultingparent,labels, andassignee.
The same binary doubles as a standalone Jira CLI for terminal use. Any bare subcommand switches to CLI mode (or force it with --cli). Output is JSON; add --pretty to indent it.
jira-mcp list-projects
jira-mcp get-issue MC-1
jira-mcp search "project = MC ORDER BY created DESC"
jira-mcp get-issue-history MC-1
jira-mcp get-related-issues MC-1
jira-mcp list-statuses MC
jira-mcp list-project-versions MC
jira-mcp list-sprints 265
jira-mcp --pretty list-users
Run jira-mcp help for the full command list.
By default the binary speaks MCP over stdio. You can also run it as an HTTP/SSE server:
jira-mcp --transport http --port 8080
GET /sse is the Server-Sent Events endpoint.POST /message is the client message endpoint.Warning: The HTTP/SSE transport carries no built-in authentication. Run it only on trusted networks and protect the endpoint with your own reverse proxy or VPN.
make test # Run tests
make test-race # Run tests with race detector
make test-cover # Run tests with coverage
make build # Build all packages
make fmt # Format code
make vet # Vet code
make clean # Remove binary
Built with GoReleaser. Tag and push to publish:
git tag -a v0.1.0 -m "Initial release"
git push origin v0.1.0
The Homebrew formula at lucasvidela94/homebrew-tap updates automatically.
Authorization header.~/.config/jira-mcp/token.json with chmod 600 permissions. The MCP client stores Basic Auth tokens in its local config file with the same restricted permissions.jira-mcp auth again.--inspect or by downloading it to a file first.MIT
Model Context Protocol (MCP) server for Jira Cloud. Search, create, update, transition, assign, and manage Jira issues directly from Claude Desktop, Cursor, OpenCode, Windsurf, and any MCP-compatible
Ringkasan umum
Model Context Protocol (MCP) server for Jira Cloud. Search, create, update, transition, assign, and manage Jira issues directly from Claude Desktop, Cursor, OpenCode, Windsurf, and any MCP-compatible AI client.
Tool
Belum ada daftar tool. Server remote mendapatkannya setelah pemeriksaan kesehatan pertama.
FAQ
Salin konfigurasi stdio untuk Cursor, Claude Desktop, Claude Code, atau VS Code di halaman ini. Konfigurasi ini memakai instalasi dari penerbit, bukan proxy PlugMCP.
Tidak ada variabel lingkungan wajib yang tercantum di catatan ini.
Jira berjalan secara lokal melalui stdio.
Terakhir diperiksa 2026-10-27. Model Context Protocol (MCP) server for Jira Cloud. Search, create, update, transition, assign, and manage Jira issues directly from Claude Desktop, Cursor, OpenCode, Windsurf, and any MCP-compatible AI client.