com.moosejudge/alces-mcp
Alces for Jira Data Center — MCP server bridging Jira DC/JSM with AI agents
Open source Open in the app JSON README (API)
About
Alces for Jira Data Center — MCP server bridging Jira DC/JSM with AI agents
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- com.moosejudge
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Added
- 2026-08-29 03:01:16
- Updated
- 2026-08-29 03:01:16
- Origin id
com.moosejudge/alces-mcp
README
# Alces for Jira Data Center
<img src="docs/media/alces-logo.svg" alt="Alces logo" width="96" height="96">
[](https://gitlab.com/moosejudge/alces-mcp/-/commits/main)
[](https://gitlab.com/moosejudge/alces-mcp/-/graphs/main/charts)
[](https://gitlab.com/moosejudge/alces-mcp/-/releases)
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/](./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](#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](https://gitlab.com/moosejudge/alces-mcp/-/releases).
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/](./docs/user/README.md) 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](#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](#usage) below always works as a fallback and is what you want for local development.
### Smithery
```bash
npx @smithery/cli@latest mcp add moosejudge/alces-mcp --client claude
```
Listing: [smithery.ai/servers/moosejudge/alces-mcp](https://smithery.ai/servers/moosejudge/alces-mcp).
### Claude Code plugin marketplace
```bash
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
```bash
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](https://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:
```bash
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:
```bash
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). Two 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. `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](https://www.npmjs.com/package/alces-mcp) directly; nothing to clone or
build. This is what every example below uses.
- **Local build (development only)** — after [Setup to develop](#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`):
```json
{
"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):
```toml
[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):
```json
{
"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.
```json
{
"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):
```json
{
"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.
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`.
**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](./CONTRIBUTING.md): The development workflow — spec, plan, TDD, review, merge.
- [AGENTS.md](./AGENTS.md): Guidance for AI agents and TDD practices.
- [docs/api-catalog.md](./docs/api-catalog.md): Catalog of implemented Jira APIs.
- [docs/developer/](./docs/developer/): Technical documentation for developers.
- [docs/user/](./docs/user/README.md): Functional documentation for users — start here if you're using Alces day-to-day rather than deploying it.
## License
[MIT](./LICENSE)