Skip to main content
Glama
multiinstance-jira-mcp

multiinstance-jira-mcp

by jmeronon-dev

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 (basic)

Jira Cloud

email + API token

Personal access token (bearer)

Jira Data Center / Server 8.14+

PAT sent as Authorization: Bearer

Browser SSO (browser)

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 instance argument → a name:KEY-1 prefix → 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_search and jira_list_projects accept allInstances: 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_issue copies 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 login run 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/jql vs /search, and accountId vs username.

  • 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 cloud

Each --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 chromium

Then 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 browser

Client 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:

  1. CLI flags (--instance …)

  2. Environment variables

  3. Config file (--config, JIRA_MCP_CONFIG, or ~/.multiinstance-jira-mcp/config.json if 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 (JIRA_<NAME>_…)

Description

name

--instance <name>

listed in JIRA_INSTANCES

Unique id (a-z 0-9 - _).

url

--url

URL, BASE_URL

Base URL, including context path if any (https://host/jira).

email

--email, --username

EMAIL, USERNAME

Account email (Cloud) or username (DC basic auth).

token

--token, --api-token, --pat

API_TOKEN, TOKEN, PAT

API token, PAT, or DC password.

tokenEnv

--token-env

TOKEN_ENV

Name of an env var that holds the token. Use it to keep secrets out of files.

auth

--auth

AUTH

basic, bearer or browser. Inferred: email+token → basic, token → bearer, neither → browser.

deployment

--deployment

DEPLOYMENT

cloud or server. Inferred from the host (*.atlassian.net → cloud).

apiVersion

--api-version

API_VERSION

3 (cloud default) or 2 (server default).

projects

--projects

PROJECTS

Project keys on this instance, used for automatic routing.

defaultProject

--default-project

DEFAULT_PROJECT

Project used by jira_create_issue when none is given.

loginUrl

--login-url

LOGIN_URL

Page opened for browser login (default: base URL).

description

--description

DESCRIPTION

Free text shown to the assistant ("client X, production support").

readOnly

--instance-read-only

READ_ONLY

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=CLA

JIRA_INSTANCES also accepts JSON in the same format as instances in the config file.

If JIRA_BASE_URL/JIRA_URL is set in your shell for other tools, it creates a default instance. 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

--config

JIRA_MCP_CONFIG

—

<home>/config.json if present

State directory

--home

JIRA_MCP_HOME

—

~/.multiinstance-jira-mcp

Default instance

--default-instance

JIRA_DEFAULT_INSTANCE

defaultInstance

—

Global read-only

--read-only

JIRA_READ_ONLY

readOnly

false

Browser login timeout (s)

--login-timeout

JIRA_LOGIN_TIMEOUT_SECONDS

loginTimeoutSeconds

300

Browser channel

--browser-channel

JIRA_BROWSER_CHANNEL

browserChannel

bundled Chromium, then Chrome, then Edge

Keep-alive interval (s, 0 = off)

--keepalive

JIRA_KEEPALIVE_SECONDS

keepAliveSeconds

300

Max attachment size (bytes)

—

JIRA_MAX_ATTACHMENT_BYTES

maxAttachmentBytes

20 MiB

Log level

--log-level

JIRA_MCP_LOG_LEVEL

—

info


How routing works

Every tool takes an optional instance argument. Issue arguments also accept extended references:

You pass

Routed to

instance: "corp"

corp

"corp:OPS-12"

corp

"https://jira.corp.local/jira/browse/OPS-12"

the instance whose URL matches that host and path

"OPS-12" with corp configured with projects: ["OPS"]

corp

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_login opens a visible Chromium/Chrome window on the Jira URL (or loginUrl). You complete SSO, MFA and anything else the identity provider asks for.

  • While you sign in, the server checks GET /rest/api/<v>/myself with 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 permissions 0600.

  • 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_login waits for waitSeconds (120 by default). After that it returns and the window stays open. The login finishes in the background, and calling jira_login again 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> and multiinstance-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

jira_list_instances

Configured instances, auth method, mapped projects, session state, default instance.

jira_whoami

Checks credentials by calling /myself. With no argument it checks all instances in parallel.

jira_login

Interactive browser SSO login for browser instances.

jira_logout

Deletes a stored session. Optionally also wipes the browser profile.

jira_add_instance

Registers a new instance at runtime (URL, auth, token, projects, …) and tests the connection.

jira_remove_instance

Removes an instance from the session.

jira_set_default_instance

Sets or clears the fallback instance.

Issues

Tool

Description

jira_search

JQL search on one instance, several instances or all of them (allInstances). Supports extra fields and pagination.

jira_get_issue

Compact view of an issue: description as text, subtasks, links, latest comments. raw: true returns the full JSON.

jira_create_issue

Creates an issue. Description in light Markdown. Optional parent, labels, priority, assignee, components, due date, custom fields.

jira_update_issue

Changes only the fields you pass, including custom fields.

jira_delete_issue

Deletes an issue (marked destructive).

jira_assign_issue

Assigns to me, an email, an accountId or a username. none unassigns.

jira_get_transitions / jira_transition_issue

Lists the available transitions, or moves the issue by transition id, transition name or target status, with an optional comment.

jira_get_comments / jira_add_comment

Reads or writes comments. Comment text accepts Markdown.

jira_add_attachment

Attaches a file from a public URL or a local path.

jira_copy_issue

Copies an issue to another instance or project, optionally with comments and back-links.

Metadata

Tool

Description

jira_list_projects

Projects, on one instance or several (allInstances).

jira_list_boards / jira_list_sprints

Jira Software boards and sprints.

jira_list_issue_types / jira_list_statuses

Issue types and statuses, globally or per project.

jira_search_users

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 SSO

The server never writes tokens to disk.

Security

  • Treat session.json like a password: it gives the same access as your browser session.

  • Prefer tokenEnv, environment variables or your client's secret prompts (such as VS Code inputs) over writing tokens into config files.

  • Tokens passed to jira_add_instance go through the AI assistant. Use that tool only for quick tests.

  • Tokens are masked in logs, and jira_list_instances never returns them.

  • Use --read-only or readOnly per instance for exploration and production sites.

  • jira_add_attachment with filePath reads files available to the user running the server.

Troubleshooting

Symptom

Fix

Several Jira instances are configured …

Pass instance, use name:KEY-1, map projects, or set a default instance.

401 on a Cloud instance

Check the email and API token pair. API tokens only work on Cloud.

401 on Data Center with a token

Check the PAT, or use --auth basic --email <username> --token <password> on older versions without PATs.

received an HTML page instead of JSON

The SSO session expired or a proxy redirected the request. Run jira_login again.

Could not launch a browser

npx playwright install chromium, or --browser-channel chrome.

jira_login returns before you finish

This is expected. Finish in the browser, then call jira_login again.

Wrong REST version

Set apiVersion (2 or 3) for that instance.

410 on search

Handled automatically: the server falls back between /search and /search/jql.

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.js

Project 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 Jira

Releases are published to npm from GitHub Actions with trusted publishing; see Releasing.

Contributing

This repository works as an agentic software factory:

  1. Open an Issue with one of the templates (bug, enhancement, new MCP tool or software factory change). Blank Issues are disabled.

  2. The 🚦 Triage agentic workflow classifies it (status, lights, complexity and area) and comments the next step.

  3. An agent (or a person) implements it following AGENTS.md and the skills in .github/skills/.

  4. Every PR must pass 🧪 validate and 📚 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

MIT

Available Tools

25 tools
jira_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 issueA
Idempotent

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 issueB
Destructive

Permanently delete an issue. Requires delete permission. Ask the user for confirmation first.

Inputs: issue (required), instance, deleteSubtasks.

jira_get_commentsGet commentsB
Read-only

Read the most recent comments of an issue as plain text.

Inputs: issue (required), instance, maxResults.

jira_get_issueGet issueA
Read-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 transitionsB
Read-only

List the workflow transitions currently available for an issue.

Inputs: issue (required), instance.

jira_list_boardsList agile boardsB
Read-only

List Jira Software boards (Scrum/Kanban), optionally filtered by project or name.

Inputs: name, instance, maxResults, projectKey.

jira_list_instancesList Jira instancesA
Read-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 typesA
Read-only

List issue types, globally or those available in a project.

Inputs: instance, projectKey.

jira_list_projectsList projectsB
Read-only

List projects visible to the account. Supports several instances at once (instances / allInstances).

Inputs: query, instance, instances, maxResults, +1 more.

jira_list_sprintsList sprintsC
Read-only

List sprints of a Scrum board.

Inputs: boardId (required), state, instance.

jira_list_statusesList statusesC
Read-only

List workflow statuses, globally or per issue type for a project.

Inputs: instance, projectKey.

jira_loginBrowser SSO loginA
Idempotent

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 sessionA
Destructive

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 instanceB
Destructive

Remove an instance from this session. Optionally also delete its stored browser session.

Inputs: name (required), deleteSession.

jira_search_usersSearch usersA
Read-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 instanceA
Idempotent

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 issueA
Idempotent

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 connectionsB
Read-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

    A3.6/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      4
      Apache 2.0