Alces for Jira Data Center

Docs: https://alces.moosejudge.com/docs

A secure, high-performance Model Context Protocol (MCP) server that bridges Atlassian Jira Data Center (DC) with AI agents like Claude and OpenAI.

Alces is an independent, community-built tool. It is not affiliated with, endorsed by, or sponsored by Atlassian. Jira® is a registered trademark of Atlassian Pty Ltd.

Overview

As Atlassian sunsets Data Center support, this server ensures that organizations can still leverage AI safely within their on-premise infrastructure. It follows open standards, the MCP specification, and a "secure by default" model.

Features

• 557 tools, broad Jira DC + JSM coverage: issues, agile boards/sprints/epics, worklogs and attachments, projects/versions/components, users/groups/permissions, JSM service desks (requests, organizations, queues, SLAs), Assets/CMDB, and instance administration — see docs/user/ for the full breakdown.
• Dual-Token Security: Differentiates between standard User PAT and Admin PAT for elevated privileges — 169 tools require the Admin PAT and are invisible to the agent without it.
• Dynamic tool-domain activation: only the core-issues domain (plus 4 meta-tools: get_api_references, list_tool_domains, activate_tool_domain, deactivate_tool_domain) is advertised by default, keeping session context small — the rest activate on request. See Tool domains below.
• Skills as MCP Resources: Agent-facing operational guidance served via the MCP resources capability — skill://core-issues, skill://jsm-service-desk, skill://assets, skill://issue-detail, skill://agile, skill://projects, skill://filters-personal-settings, skill://users-groups-permissions, skill://admin.

Install to use

Data Center only. Alces does not support Jira Cloud (*.atlassian.net). If your Jira URL ends in atlassian.net, this tool won't work — Data Center or Server only.

Just want to talk to your Jira DC instance through Claude Desktop, without cloning or building anything? Install the pre-built bundle:

1. Download the latest alces-mcp-<version>.mcpb from the GitLab Releases page.
2. In Claude Desktop: Settings → Extensions → Advanced settings → Extension Developer → "Install Extension…", then select the downloaded file.
3. Enter your Jira URL and PAT(s) when prompted — these are stored via your OS keychain, never as plaintext.

Once connected, see docs/user/ for what you can do and how to ask for it.

If you're integrating Alces into a coding agent instead of Claude Desktop, skip to Usage below.

Install via a marketplace or registry

Beyond the .mcpb download above, Alces is also listed on four package-manager-style channels. These are the fastest path if your client supports one of them; the manual per-client config in Usage below always works as a fallback and is what you want for local development.

Smithery

npx @smithery/cli@latest mcp add moosejudge/alces-mcp --client claude

Listing: smithery.ai/servers/moosejudge/alces-mcp.

Claude Code plugin marketplace

claude plugin marketplace add https://gitlab.com/moosejudge/mcp-marketplace.git
claude plugin install alces-mcp@mcp-marketplace

Use the full https://gitlab.com/... URL — the bare moosejudge/mcp-marketplace shorthand resolves as a GitHub repo shorthand in Claude Code and fails, since this marketplace is hosted on GitLab.

Codex CLI plugin marketplace

codex plugin marketplace add https://gitlab.com/moosejudge/alces-mcp.git
codex plugin add alces-mcp@alces-mcp

Official MCP Registry

Alces is listed at registry.modelcontextprotocol.io under com.moosejudge/alces-mcp, with a real npm package reference — any MCP-Registry-aware client can resolve alces-mcp from there directly.

Setup to develop

Contributing, or working from an unreleased commit instead of the published npm package:

1. Clone the repository.
2. Install dependencies:

   npm install

3. Copy .env.example to .env and fill in JIRA_URL, JIRA_USER_TOKEN, and (optionally) JIRA_ADMIN_TOKEN.
4. Build the project:

   npm run build

Usage

Connect Alces to a coding agent's own MCP config. Same three environment variables everywhere (JIRA_URL, JIRA_USER_TOKEN, JIRA_ADMIN_TOKEN — the last one optional, enabling the 169 admin tools when set). Three more optional variables, not needed in the config examples below: JIRA_TIMEOUT_MS sets the request timeout (in milliseconds) for every call Alces makes to Jira — defaults to 30000 (30s); raise it if your instance is slow to respond to large requests. ALCES_TOOL_GROUPS pre-activates a fixed set of tool domains at startup instead of the core-issues default. ALCES_TOKEN_ESCALATION_DOMAINS opts specific tool domains into the token-escalation mechanism (see Token escalation) — unset by default, meaning no tool may use JIRA_ADMIN_TOKEN via token escalation. JIRA_SESSION_USERNAME/JIRA_SESSION_PASSWORD (a real Jira DC account's username/password, not a PAT) enable session-cookie auth for the small set of legacy avatar upload/crop/finalize tools that don't work over PAT bearer auth alone — see .env.example and docs/developer/admin.md for details. Set JIRA_SESSION_USERNAME to the same Jira account as JIRA_USER_TOKEN, and don't use an administrator account for it: those avatar tools drop the PAT bearer header and authenticate with this account's session cookie instead, so whichever token the call selected, the write runs under this account's permissions and Jira credits it in the audit trail — and they're user-tier tools with no admin gate and no escalation disclosure. Alces prints a startup warning on stderr if the two accounts differ. They're available as optional fields in the .mcpb/Claude Code plugin config UI too; every other tool is unaffected if you leave them unset. ALCES_TOOL_GROUPS and ALCES_TOKEN_ESCALATION_DOMAINS are both plugin-config fields there as well, with their defaults (core-issues and empty/no-escalation respectively) shown in the UI.

Two ways to run the server, in every config below:

• npx (recommended) — command: "npx", args: ["-y", "alces-mcp"]. Runs the published alces-mcp npm package directly; nothing to clone or build. This is what every example below uses.
• Local build (development only) — after Setup to develop above, swap in command: "node", args: ["/path/to/alces-mcp/build/index.js"] (or the TOML equivalent for Codex CLI) instead of the npx form, to run against your own clone/unreleased changes.

Either way, npx alces-mcp --version prints the installed version and npx alces-mcp --help prints a one-line usage reminder; both exit immediately without starting the MCP server, so they're safe to run when you just want to check what you have installed. (-v and -h work too.)

Claude Code

.mcp.json in your project root (or run claude mcp add --transport stdio alces -- npx -y alces-mcp):

{
  "mcpServers": {
    "alces": {
      "command": "npx",
      "args": ["-y", "alces-mcp"],
      "env": {
        "JIRA_URL": "https://your-jira-instance.com",
        "JIRA_USER_TOKEN": "your-user-pat",
        "JIRA_ADMIN_TOKEN": "your-admin-pat"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml (or .codex/config.toml for a project-scoped server):

[mcp_servers.alces]
command = "npx"
args = ["-y", "alces-mcp"]
env = { JIRA_URL = "https://your-jira-instance.com", JIRA_USER_TOKEN = "your-user-pat", JIRA_ADMIN_TOKEN = "your-admin-pat" }

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "alces": {
      "command": "npx",
      "args": ["-y", "alces-mcp"],
      "env": {
        "JIRA_URL": "https://your-jira-instance.com",
        "JIRA_USER_TOKEN": "your-user-pat",
        "JIRA_ADMIN_TOKEN": "your-admin-pat"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json, in VS Code's extension global storage — not a repo-relative file. On Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS/Windows equivalents under their own User/globalStorage paths). Easiest to add via Cline's built-in MCP marketplace/settings UI rather than hand-editing this path.

{
  "mcpServers": {
    "alces": {
      "command": "npx",
      "args": ["-y", "alces-mcp"],
      "env": {
        "JIRA_URL": "https://your-jira-instance.com",
        "JIRA_USER_TOKEN": "your-user-pat",
        "JIRA_ADMIN_TOKEN": "your-admin-pat"
      }
    }
  }
}

Gemini CLI

~/.gemini/settings.json (global) or .gemini/settings.json (project):

{
  "mcpServers": {
    "alces": {
      "command": "npx",
      "args": ["-y", "alces-mcp"],
      "env": {
        "JIRA_URL": "https://your-jira-instance.com",
        "JIRA_USER_TOKEN": "your-user-pat",
        "JIRA_ADMIN_TOKEN": "your-admin-pat"
      }
    }
  }
}

Tool domains

557 tools is a lot to advertise on every tools/list call regardless of what a given session actually needs, so as of 1.0.0 tools are grouped into 9 domains and only activated on demand:

core-issues, jsm-service-desk, assets, issue-detail, agile, projects, filters-personal-settings, users-groups-permissions, admin

By default, only core-issues is active, alongside 4 always-visible meta-tools:

• get_api_references — returns references to the Jira API documentation and implemented endpoints.
• list_tool_domains — lists all 9 domains, their tool counts, and which are currently active.
• activate_tool_domain — activates one or more domains for the rest of the session (accepts an array of domain names) and emits the MCP notifications/tools/list_changed notification so clients that support it pick up the newly-visible tools automatically.
• deactivate_tool_domain — the inverse, for trimming an active domain back out.

Both activate_tool_domain and deactivate_tool_domain validate the domain names they're given: unknown names are rejected and reported back rather than silently ignored, while any valid names in the same request still take effect.

A client that doesn't process list_changed (or a script that wants everything visible from the first tools/list call) can instead set ALCES_TOOL_GROUPS — a comma-separated list of domain names — before starting the server, e.g. ALCES_TOOL_GROUPS=core-issues,agile,admin. Unknown domain names are logged as a warning to stderr at startup and otherwise ignored (the valid subset still activates); the same validate-and-report behavior applies to activate_tool_domain and deactivate_tool_domain. It's also available as an optional field ("Tool domains to activate at startup") in the .mcpb/Claude Code plugin config UI, alongside the Jira connection settings.

Credentials and ALCES_TOOL_GROUPS are both read once, at process start. A running server doesn't re-read its environment — rotating JIRA_ADMIN_TOKEN, adding it for the first time, or changing ALCES_TOOL_GROUPS on an already-running process has no effect until the process is restarted. activate_tool_domain's success response and list_tool_domains's active: true are both accurate for the server's current process state, but neither one tells you a restart is what's actually needed if you just changed the environment out from under it — if a domain or token you just configured still doesn't seem to take effect, restart the server before assuming something's broken.

All tools remain callable by name regardless of activation state — domain activation only controls what's advertised in tools/list, not what's reachable. Calling a tool from an inactive domain by name still works.

get_api_references also stays always-visible, independent of domain activation, for inspecting the full API catalog without activating anything.

Token escalation

Most tools can fall back to the elevated JIRA_ADMIN_TOKEN credential instead of JIRA_USER_TOKEN for one call — useful when a normal user's own permissions are the actual obstacle, not a bug. A tool is eligible for this unless it already requires JIRA_ADMIN_TOKEN outright (nothing to escalate to), is a meta-tool with no underlying Jira domain (get_api_references, list_tool_domains, activate_tool_domain, deactivate_tool_domain — no client selection happens for these), or is in a fixed set of 41 tools excluded by design — never eligible no matter what. That set is two categories: basic issue interaction (creating, editing, transitioning, assigning, commenting on, logging work on, attaching to, voting on or watching a work item, in Jira, JSM or Assets alike — borrowing the admin identity there would rewrite Jira's own record of who did what) and self-scoped personal actions (your own profile, preferences, permissions, favourites, share scope or session, where "as someone else" changes what the call means rather than who signs it). Board-level moves and ranking, deletes, and issue metadata that carries no author stay eligible on purpose — see docs/developer/token-escalation-and-gates.md for the full list and the test that keeps it current. An ineligible tool never advertises a useAdminToken argument, and sending it one anyway — with either true or false — is refused with an error naming why that tool can never use the admin credential, rather than being accepted and quietly ignored. This is off by default: set ALCES_TOKEN_ESCALATION_DOMAINS (a comma-separated list of tool domains, e.g. ALCES_TOKEN_ESCALATION_DOMAINS=projects,jsm-service-desk) to opt specific domains in — no eligible tool can use the admin credential until its domain is listed here. Once a domain is opted in, two trigger paths are live for its eligible tools, not just one: (1) automatic fallback — within a normal call made with JIRA_USER_TOKEN, the one request that gets a real 403 is transparently retried with JIRA_ADMIN_TOKEN (earlier requests in the same call are not replayed), with no argument needed from the caller; and (2) explicit request — the caller (an agent, or you on request) can pass useAdminToken: true to skip the user-token attempt and call directly with JIRA_ADMIN_TOKEN. Either path discloses itself in the response text when it fires. See docs/specs/2026-09-16-tool-permission-audit-and-token-escalation-design.md for the full rationale.

Stability

As of 1.0.0, registered tool names and their required-field schemas are stable: removing a tool, or adding a new required field to an existing tool, is a breaking change and ships in a major version. New tools, new optional fields, and new tool domains (e.g. via the tool-domain activation mechanism) are additive and ship in minor versions.

Documentation

• CONTRIBUTING.md: The development workflow — spec, plan, TDD, review, merge.
• AGENTS.md: Guidance for AI agents and TDD practices.
• docs/api-catalog.md: Catalog of implemented Jira APIs.
• docs/developer/: Technical documentation for developers.
• docs/user/: Functional documentation for users — start here if you're using Alces day-to-day rather than deploying it.

License

MIT