multiinstance-jira-mcp
This MCP server connects AI assistants to multiple Jira Cloud/Data Center sites simultaneously, with per-instance auth (API token, PAT, or browser SSO) and automatic routing.
Manage instances: list configured instances, check credentials (
jira_whoami), add/remove instances at runtime, set a default instance, and log in/out via browser SSO (per-instance cookie jars and profiles).Search: run JQL on one instance, a named list, or all instances at once (results grouped per instance; partial failures tolerated), and list projects across instances.
Read issues: fetch compact issue views (description as text, subtasks, links, latest comments) or raw JSON, plus comments, workflow transitions, boards, sprints, issue types, statuses, and users.
Write issues: create, update, delete, assign, and transition issues; add comments and attachments (from URL or local file path); descriptions/comments accept light Markdown (converted to ADF on Cloud).
Cross-instance work: copy an issue to another instance/project, optionally with priority, comments, and back-links.
Routing & safety: automatic routing by
instance,name:KEY-1prefix, browse URL, project-key mapping, default or single instance; ambiguous calls error with options. Supports global or per-instance read-only mode, secret masking, and tokens never written to disk.
Authenticates against Atlassian-hosted Jira Cloud sites (e.g. *.atlassian.net) using an email and Atlassian API token via basic auth, with deployment/API version automatically inferred from the host.
Core integration target: connects to one or more Jira sites (Jira Cloud and Jira Data Center/Server) and exposes tools for searching issues across instances, listing projects, retrieving and creating issues, copying issues between instances, and adding links back to originals. Supports API tokens, personal access tokens, and browser SSO logins, with automatic per-instance routing, cross-instance search aggregation, and an optional read-only mode.
Works with Jira Software projects on Cloud and Data Center/Server: issue search (JQL), project listing, issue creation with default project support, issue copying between sites with reciprocal links, and routing by project key or pasted issue URL. Handles Cloud vs Data Center differences such as REST v3 vs v2, ADF vs plain-text descriptions, and accountId vs username.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@multiinstance-jira-mcp Search all my Jira instances for open bugs assigned to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
multiinstance-jira-mcp
A Model Context Protocol server that connects AI assistants (Claude, Cursor, VS Code Copilot, OpenCode, …) to any number of Jira sites at the same time: Jira Cloud and Jira Data Center / Server, each with its own authentication method:
Method | Use it for | How it authenticates |
API token ( | Jira Cloud |
|
Personal access token ( | Jira Data Center / Server 8.14+ | PAT sent as |
Browser SSO ( | Any site behind SAML / OIDC / corporate SSO where tokens are not allowed | A real browser window opens, you sign in, the Jira session cookies are stored per instance |
You can pass tokens as command-line arguments, environment variables, a config file, or add instances while the server is running.
What makes it different
1..N instances in one server. A Cloud site with an API token, an internal Data Center with a PAT and a partner's Jira behind SSO can all be configured together.
Automatic routing. Every call is sent to the right instance using, in order: the
instanceargument → aname:KEY-1prefix → the host of a pasted issue URL → project-key mapping → the default instance → the only instance. If a call is ambiguous, the server asks for the instance and names the options.Search across instances.
jira_searchandjira_list_projectsacceptallInstances: true(or a list of instances) and return results grouped per instance. If one instance fails, you still get the results from the others.Copy between instances.
jira_copy_issuecopies an issue from one site to another and adds a link back to the original on each issue.Independent sessions. Each browser-auth instance has its own cookie jar and its own browser profile. Logins don't block tool calls, and a
loginrun from a terminal is picked up by a running server without a restart.Cloud and Data Center differences handled for you. This covers REST v3 vs v2, ADF vs plain-text descriptions,
/search/jqlvs/search, andaccountIdvsusername.Read-only mode. You can turn off writes globally or for one instance.
Related MCP server: MCP Jira
Quick start
Requires Node.js 20+.
One Jira Cloud site (API token)
npx -y multiinstance-jira-mcp --url https://acme.atlassian.net --email me@acme.com --token "$JIRA_API_TOKEN"Several sites at once
npx -y multiinstance-jira-mcp \
--instance cloud --url https://acme.atlassian.net --email me@acme.com --token "$CLOUD_TOKEN" --projects WEB,APP \
--instance dc --url https://jira.corp.local/jira --token "$DC_PAT" --projects OPS,INFRA \
--instance partner --url https://jira.partner.com --auth browser \
--default-instance cloudEach --instance <name> starts a new block. The flags after it (--url, --email, --token, --auth, …) apply to that instance until the next --instance.
Browser SSO
Install a browser for Playwright once. You can skip this step if you set --browser-channel chrome to use your installed Chrome or Edge.
npx playwright install chromiumThen either ask the assistant to "log in to the partner Jira", which calls jira_login, or run the login from a terminal:
npx -y multiinstance-jira-mcp login partner --instance partner --url https://jira.partner.com --auth browserClient configuration
The server speaks MCP over stdio. Your client starts it, so you normally don't run it by hand.
{
"mcpServers": {
"jira": {
"command": "npx",
"args": [
"-y", "multiinstance-jira-mcp",
"--instance", "cloud", "--url", "https://acme.atlassian.net", "--email", "me@acme.com", "--token", "ATATT3x...",
"--instance", "corp", "--url", "https://jira.corp.local", "--auth", "browser", "--projects", "OPS"
]
}
}
}{
"mcpServers": {
"jira": {
"command": "npx",
"args": ["-y", "multiinstance-jira-mcp"],
"env": {
"JIRA_INSTANCES": "cloud,corp",
"JIRA_CLOUD_URL": "https://acme.atlassian.net",
"JIRA_CLOUD_EMAIL": "me@acme.com",
"JIRA_CLOUD_API_TOKEN": "ATATT3x...",
"JIRA_CORP_URL": "https://jira.corp.local",
"JIRA_CORP_PAT": "NjM2...",
"JIRA_CORP_PROJECTS": "OPS,INFRA",
"JIRA_DEFAULT_INSTANCE": "cloud"
}
}
}
}{
"inputs": [
{ "id": "cloudToken", "type": "promptString", "description": "Jira Cloud API token", "password": true }
],
"servers": {
"jira": {
"type": "stdio",
"command": "npx",
"args": [
"-y", "multiinstance-jira-mcp",
"--instance", "cloud", "--url", "https://acme.atlassian.net", "--email", "me@acme.com", "--token", "${input:cloudToken}",
"--instance", "corp", "--url", "https://jira.corp.local", "--auth", "browser"
]
}
}
}{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"jira": {
"type": "local",
"command": ["npx", "-y", "multiinstance-jira-mcp", "--config", "~/.multiinstance-jira-mcp/config.json"],
"enabled": true,
"environment": {
"JIRA_CLOUD_TOKEN": "ATATT3x..."
}
}
}
}More ready-to-copy files live in examples/.
Configuring instances
There are three startup sources. They are merged per instance name, field by field. The highest priority wins:
CLI flags (
--instance …)Environment variables
Config file (
--config,JIRA_MCP_CONFIG, or~/.multiinstance-jira-mcp/config.jsonif it exists)
So you can, for example, keep URLs in a config file and pass only the tokens as arguments. You can also add instances while the server is running with the jira_add_instance tool. Those are kept in memory for the current session only.
Instance fields
Field | CLI flag | Env suffix ( | Description |
|
| listed in | Unique id ( |
|
|
| Base URL, including context path if any ( |
|
|
| Account email (Cloud) or username (DC basic auth). |
|
|
| API token, PAT, or DC password. |
|
|
| Name of an env var that holds the token. Use it to keep secrets out of files. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Project keys on this instance, used for automatic routing. |
|
|
| Project used by |
|
|
| Page opened for browser login (default: base URL). |
|
|
| Free text shown to the assistant ("client X, production support"). |
|
|
| Disable write tools on this instance. |
Instance flags given before any --instance configure an instance called default.
Environment variables
Single instance:
JIRA_BASE_URL=https://acme.atlassian.net # or JIRA_URL
JIRA_EMAIL=me@acme.com
JIRA_API_TOKEN=ATATT3x...
JIRA_INSTANCE_NAME=acme # optional, default "default"Many instances: list the names, then prefix every field with JIRA_<NAME>_. The name is upper-cased, and anything that isn't a letter or digit becomes _.
JIRA_INSTANCES=cloud,client-a
JIRA_CLOUD_URL=https://acme.atlassian.net
JIRA_CLOUD_EMAIL=me@acme.com
JIRA_CLOUD_API_TOKEN=ATATT3x...
JIRA_CLIENT_A_URL=https://jira.client-a.com
JIRA_CLIENT_A_AUTH=browser
JIRA_CLIENT_A_PROJECTS=CLAJIRA_INSTANCES also accepts JSON in the same format as instances in the config file.
If
JIRA_BASE_URL/JIRA_URLis set in your shell for other tools, it creates adefaultinstance. Unset it in the MCP client's environment if you don't want that.
Config file
{
"defaultInstance": "cloud",
"loginTimeoutSeconds": 300,
"instances": {
"cloud": {
"url": "https://acme.atlassian.net",
"email": "me@acme.com",
"tokenEnv": "JIRA_CLOUD_TOKEN",
"projects": ["WEB", "APP"],
"description": "Product development"
},
"corp": {
"url": "https://jira.corp.local/jira",
"tokenEnv": "JIRA_CORP_PAT",
"projects": ["OPS", "INFRA"]
},
"partner": {
"url": "https://jira.partner.com",
"auth": "browser",
"readOnly": true
}
}
}instances can also be an array of objects with a name field. See examples/config.example.json.
Global settings
Setting | CLI | Env | Config file | Default |
Config file |
|
| — |
|
State directory |
|
| — |
|
Default instance |
|
|
| — |
Global read-only |
|
|
|
|
Browser login timeout (s) |
|
|
|
|
Browser channel |
|
|
| bundled Chromium, then Chrome, then Edge |
Keep-alive interval (s, 0 = off) |
|
|
|
|
Max attachment size (bytes) | — |
|
| 20 MiB |
Log level |
|
| — |
|
How routing works
Every tool takes an optional instance argument. Issue arguments also accept extended references:
You pass | Routed to |
|
|
|
|
| the instance whose URL matches that host and path |
|
|
anything else | the default instance, or the only instance |
If none of these rules matches and several instances exist, the tool returns an error listing the instances. The assistant can then ask you which one to use.
Browser SSO in detail
jira_loginopens a visible Chromium/Chrome window on the Jira URL (orloginUrl). You complete SSO, MFA and anything else the identity provider asks for.While you sign in, the server checks
GET /rest/api/<v>/myselfwith the browser's own cookie jar. As soon as Jira accepts the session, it stores only the cookies that belong to the Jira host. The file is~/.multiinstance-jira-mcp/instances/<name>/session.json, with permissions0600.Each instance has a persistent browser profile, so the identity provider usually remembers you and later logins take one click.
MCP clients often time out long tool calls, so
jira_loginwaits forwaitSeconds(120 by default). After that it returns and the window stays open. The login finishes in the background, and callingjira_loginagain reports the result.A keep-alive loop pings each browser session regularly so idle sessions don't expire. Cookies the server rotates (for example a refreshed
JSESSIONID) are saved automatically. Once the identity provider's session really expires, you need to log in interactively again.CLI equivalents:
multiinstance-jira-mcp login <instance>andmultiinstance-jira-mcp logout <instance> [--forget-profile].
Tools
All tools accept instance unless noted otherwise. Issue parameters accept KEY-1, instance:KEY-1 or a browse URL.
Instances and authentication
Tool | Description |
| Configured instances, auth method, mapped projects, session state, default instance. |
| Checks credentials by calling |
| Interactive browser SSO login for |
| Deletes a stored session. Optionally also wipes the browser profile. |
| Registers a new instance at runtime (URL, auth, token, projects, …) and tests the connection. |
| Removes an instance from the session. |
| Sets or clears the fallback instance. |
Issues
Tool | Description |
| JQL search on one instance, several instances or all of them ( |
| Compact view of an issue: description as text, subtasks, links, latest comments. |
| Creates an issue. Description in light Markdown. Optional parent, labels, priority, assignee, components, due date, custom fields. |
| Changes only the fields you pass, including custom fields. |
| Deletes an issue (marked destructive). |
| Assigns to |
| Lists the available transitions, or moves the issue by transition id, transition name or target status, with an optional comment. |
| Reads or writes comments. Comment text accepts Markdown. |
| Attaches a file from a public URL or a local path. |
| Copies an issue to another instance or project, optionally with comments and back-links. |
Metadata
Tool | Description |
| Projects, on one instance or several ( |
| Jira Software boards and sprints. |
| Issue types and statuses, globally or per project. |
| User search, or assignable users for a project. |
Rich text: on REST v3 instances (Cloud), Markdown in descriptions and comments is converted to Atlassian Document Format (headings, lists, code blocks, quotes, bold, inline code, links). On REST v2 instances the text is sent as-is, so you can use Jira wiki markup there.
Files on disk
~/.multiinstance-jira-mcp/ (override with --home / JIRA_MCP_HOME)
├── config.json optional config file
└── instances/
└── <name>/
├── session.json browser-session cookies (0600)
└── browser-profile/ persistent browser profile for SSOThe server never writes tokens to disk.
Security
Treat
session.jsonlike a password: it gives the same access as your browser session.Prefer
tokenEnv, environment variables or your client's secret prompts (such as VS Codeinputs) over writing tokens into config files.Tokens passed to
jira_add_instancego through the AI assistant. Use that tool only for quick tests.Tokens are masked in logs, and
jira_list_instancesnever returns them.Use
--read-onlyorreadOnlyper instance for exploration and production sites.jira_add_attachmentwithfilePathreads files available to the user running the server.
Troubleshooting
Symptom | Fix |
| Pass |
| Check the email and API token pair. API tokens only work on Cloud. |
| Check the PAT, or use |
| The SSO session expired or a proxy redirected the request. Run |
|
|
| This is expected. Finish in the browser, then call |
Wrong REST version | Set |
| Handled automatically: the server falls back between |
Set --log-level debug to log every request (method and path) to stderr.
Development
npm install
npm run typecheck
npm test # vitest: CLI, config merge, routing, cookies, ADF, REST client, MCP end-to-end
npm run build # → dist/
npm run dev -- --instance cloud --url https://acme.atlassian.net --email me@acme.com --token "$TOKEN"
npm run inspect # MCP Inspector against dist/index.jsProject layout:
src/
├── index.ts entry point & CLI subcommands (serve, login, logout, instances)
├── cli.ts argument parser (instance-scoped flag blocks)
├── server.ts McpServer + dynamic instructions
├── config/ types, normalisation/inference, multi-source loading
├── auth/ auth providers, cookie jar, Playwright browser login
├── instances/ registry & routing, login manager, keep-alive
├── jira/ REST client, ADF <-> text, compact formatting
└── tools/ MCP tool definitions (instances, issues, metadata, transfer)
tests/ vitest suites with a fake JiraReleases are published to npm from GitHub Actions with trusted publishing; see Releasing.
Contributing
This repository works as an agentic software factory:
Open an Issue with one of the templates (bug, enhancement, new MCP tool or software factory change). Blank Issues are disabled.
The
🚦 Triageagentic workflow classifies it (status, lights, complexity and area) and comments the next step.An agent (or a person) implements it following
AGENTS.mdand the skills in.github/skills/.Every PR must pass
🧪 validateand📚 docs. Documentation-only and small, low-risk changes can merge on their own (🌙 lights-out); everything else is reviewed by a person.
The full process is in the project wiki, starting with Software factory.
Acknowledgements
Inspired by the browser-SSO idea in @svasimahmed283/jira-mcp. This project is an independent implementation built around multi-instance support and token authentication.
License
Available Tools
25 toolsjira_add_attachmentAttach a fileA
Attach a file to an issue, either downloaded from a public URL or read from a local path on the machine running this server.
Inputs: issue (required), url, filePath, filename, +1 more.
jira_add_commentAdd commentB
Add a comment to an issue (light Markdown supported).
Inputs: body (required), issue (required), instance.
jira_add_instanceAdd a Jira instance at runtimeA
Register an additional Jira instance for this session (kept in memory; add it to your MCP config to make it permanent). Auth is inferred: email+token → basic (Jira Cloud API token), token only → bearer (Data Center PAT), nothing → browser SSO. Note: a token passed here is visible to the assistant; prefer configuring secrets in the MCP config.
Inputs: url (required), name (required), auth, email, +9 more.
jira_assign_issueAssign issueAIdempotent
Assign an issue. user accepts 'me', an email/display name, a Cloud accountId or a Data Center username. Use 'none' to unassign.
Inputs: user (required), issue (required), instance.
jira_copy_issueCopy issue between instancesA
Copy an issue (summary, description, labels, optionally priority and comments) from one Jira instance to a project on another instance — or the same one. Adds cross-reference comments when linkBack is true.
Inputs: issue (required), targetProject (required), targetInstance (required), linkBack, +4 more.
jira_create_issueCreate issueB
Create an issue. The description accepts light Markdown (headings, lists, bold, code, links, code fences) and is converted to the format the instance expects. The instance is routed by project key mapping or the 'instance' argument.
Inputs: summary (required), labels, parent, boardId, +9 more.
jira_delete_issueDelete issueBDestructive
Permanently delete an issue. Requires delete permission. Ask the user for confirmation first.
Inputs: issue (required), instance, deleteSubtasks.
jira_get_commentsGet commentsBRead-only
Read the most recent comments of an issue as plain text.
Inputs: issue (required), instance, maxResults.
jira_get_issueGet issueARead-only
Read an issue: summary, status, people, description as text, subtasks, links and latest comments. Set raw=true for the full Jira JSON.
Inputs: issue (required), raw, fields, instance.
jira_get_transitionsList available transitionsBRead-only
List the workflow transitions currently available for an issue.
Inputs: issue (required), instance.
jira_list_boardsList agile boardsBRead-only
List Jira Software boards (Scrum/Kanban), optionally filtered by project or name.
Inputs: name, instance, maxResults, projectKey.
jira_list_instancesList Jira instancesARead-only
List every configured Jira instance (name, URL, deployment, auth method, mapped projects, session state) and the default instance. Call this first when unsure which instance to target.
Inputs: no named parameters.
jira_list_issue_typesList issue typesARead-only
List issue types, globally or those available in a project.
Inputs: instance, projectKey.
jira_list_projectsList projectsBRead-only
List projects visible to the account. Supports several instances at once (instances / allInstances).
Inputs: query, instance, instances, maxResults, +1 more.
jira_list_sprintsList sprintsCRead-only
List sprints of a Scrum board.
Inputs: boardId (required), state, instance.
jira_list_statusesList statusesCRead-only
List workflow statuses, globally or per issue type for a project.
Inputs: instance, projectKey.
jira_loginBrowser SSO loginAIdempotent
Open a browser window so the user can sign in to a Jira instance that uses auth 'browser' (SSO/SAML/OIDC). Session cookies are stored per instance. If sign-in takes longer than waitSeconds, the window stays open and the login completes in the background — call jira_login again (or jira_whoami) to check.
Inputs: force, instance, waitSeconds.
jira_logoutForget a browser sessionADestructive
Delete the stored browser-session cookies of an instance. With forgetBrowserProfile=true also wipes the dedicated browser profile, so the identity provider asks for credentials again.
Inputs: instance, forgetBrowserProfile.
jira_remove_instanceRemove a Jira instanceBDestructive
Remove an instance from this session. Optionally also delete its stored browser session.
Inputs: name (required), deleteSession.
jira_searchSearch issues with JQLARead-only
Run a JQL query. Target one instance, a list of instances or all of them at once (allInstances=true) — results are grouped per instance and a failure on one instance does not hide the others.
Inputs: jql (required), fields, startAt, instance, +4 more.
jira_search_usersSearch usersARead-only
Find users by name/email. With projectKey, only users assignable in that project are returned.
Inputs: query, instance, maxResults, projectKey.
jira_set_default_instanceSet default Jira instanceAIdempotent
Choose the instance used when a call cannot be routed automatically. Omit name to clear it.
Inputs: name.
jira_transition_issueTransition issueA
Move an issue through its workflow. 'transition' may be a transition id, a transition name or the target status name.
Inputs: issue (required), transition (required), comment, instance.
jira_update_issueUpdate issueAIdempotent
Update fields of an issue. Only the provided fields change. Use jira_transition_issue to change status and jira_assign_issue to change assignee.
Inputs: issue (required), labels, parent, dueDate, +6 more.
jira_whoamiCheck Jira connectionsBRead-only
Verify connectivity and credentials by calling /myself. Without arguments it checks every configured instance in parallel.
Inputs: instance.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools map to a distinct resource+action, and instance-management tools (add/remove/set_default/login/logout) are clearly separable from issue operations. Minor overlap exists: jira_get_comments duplicates what jira_get_issue already returns, and jira_whoami partially overlaps jira_list_instances in surfacing instance/auth state.
Every tool uses the jira_ prefix with snake_case verb_noun phrasing (get_issue, create_issue, list_projects, add_attachment, copy_issue). The only mild deviation is jira_whoami, which is a standard, well-understood identifier rather than an inconsistency.
25 tools is at the heavy end but justified by covering multiple distinct areas: instance/auth management, issue CRUD, workflow transitions, and Jira Software metadata (boards, sprints, statuses, users). Nothing feels obviously redundant, though a few list_* tools could theoretically be consolidated.
Covers the core Jira lifecycle thoroughly: issue CRUD, transitions, assignment, comments, attachments, cross-instance copy, and metadata lookups. Gaps remain around comment update/delete, issue linking, worklogs, and attachment retrieval/removal, but these are minor for most agent workflows.
Maintenance
Related MCP Connectors
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Every email and calendar account you connect, for AI agents, with permissions and approvals.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Atlassian products (Confluence and Jira) through natural language, supporting both Cloud and Server/Data Center deployments. Allows searching, creating, and managing content across Jira issues and Confluence pages with flexible authentication options.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Jira Cloud and Server/Data Center deployments for issue management, project tracking, and workflow automation. Supports multiple authentication methods including API tokens, OAuth 2.0, and personal access tokens.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage Jira tasks, issues, and projects using Atlassian's modern scoped API tokens, with safety features like read-only default and delete confirmation.69 npm4Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search, create, update, and transition Jira issues and Confluence pages, add comments, and manage Atlassian content across Cloud and Server/Data Center deployments.MIT