alces-mcp

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

• 556 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 — 120 tools require the Admin PAT and are invisible to the agent without it.
• Dynamic tool-domain activation: only the core-issues domain (plus 3 meta-tools) 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:

• Download the latest alces-mcp-<version>.mcpb from the GitLab Releases page.
• In Claude Desktop: Settings → Extensions → Advanced settings → Extension Developer → "Install Extension…", then select the downloaded file.
• 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:

• Clone the repository.
• Install dependencies:

  npm install
  

• Copy .env.example to .env and fill in JIRA_URL, JIRA_USER_TOKEN, and (optionally) JIRA_ADMIN_TOKEN.
• 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 120 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. 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. 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.

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.

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

556 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 3 always-visible meta-tools:

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

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

Changelog

[1.0.2] - 2026-09-16

Fixed

• transition_issue now accepts an optional fields param, passed straight through to Jira's transitions endpoint — fixes a transition whose screen collects a field (most commonly resolution on a "Resolve"/"Done" transition) silently leaving that field unset. The transition itself succeeded either way, but the issue stayed matching resolution = Unresolved in every query indefinitely despite looking closed to a human, with no way to correct it afterward (update_issue can't set resolution on a standard configuration — it isn't on the edit screen).
• get_transitions gains an optional includeFields param to discover a transition's required fields before invoking it, so this class of silent under-fill can be caught up front instead of after the fact.

Added

• ALCES_TOOL_GROUPS is now exposed as a configurable startup variable ("Tool domains to activate at startup") in the .mcpb/Claude Code plugin config UI, not just as a raw environment variable — the server already honored it correctly, there was just no way to set it without editing the launch environment directly.
• Documented that credentials and ALCES_TOOL_GROUPS are both read once at process start — a running server needs a restart, not just an environment change, to pick up either one. Nothing in activate_tool_domain's success response or list_tool_domains's active: true indicates a restart is what's actually needed, which cost real debugging time before this was root-caused.