custom-atlassian-mcp

A small, self-hosted Model Context Protocol server that exposes Jira and Confluence Cloud to any MCP-compatible client (Claude Code, Claude Desktop, GitHub Copilot Agents, etc.) over stdio.

Built as a lightweight alternative to the (currently unavailable) public Confluence MCP — one Atlassian site, one API token, no frameworks.

What you get

Jira

• jira_search — run a JQL query, get a compact issue list

• jira_get_issue — full issue with description and recent comments (ADF → text)

• jira_add_comment — append a plain-text comment

• jira_update_issue — edit summary, description, assignee, priority, labels

• jira_create_issue — create issues, optionally linked to an epic or parent

• jira_transition_issue — list transitions or move an issue through workflow

• jira_list_sprints — list sprints for a Jira Software board (Agile API)

• jira_add_issues_to_sprint — move issues into a sprint

Confluence

• confluence_search — CQL search across spaces and pages

• confluence_get_page — fetch a page as plain text or raw storage-format XHTML

• confluence_create_page — create a page under a space (optionally under a parent)

• confluence_update_page — update body/title; supports drafts and publishing

Related MCP server: Jira MCP Server

Requirements

• Node.js 18+ (uses the built-in fetch)

• An Atlassian Cloud site and an API token (create one at https://id.atlassian.com/manage-profile/security/api-tokens)

Install

git clone https://github.com/shamshodisaev/custom-atlassian-mcp.git
cd custom-atlassian-mcp
npm install
npm run build

npm run build compiles TypeScript to dist/ and marks dist/index.js executable.

Configure

The server reads three environment variables:

For local runs you can copy .env.example to .env and fill it in — but the MCP server itself does not load .env automatically. Either export the vars in your shell, launch the server via node --env-file=.env dist/index.js, or pass them through your MCP client's config (see below).

Wire it into an MCP client

Claude Code

Add an entry to your Claude Code MCP config (typically ~/.claude.json under mcpServers, or via claude mcp add):

{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/absolute/path/to/custom-atlassian-mcp/dist/index.js"],
      "env": {
        "ATLASSIAN_SITE": "your-org.atlassian.net",
        "ATLASSIAN_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "ATATT3x..."
      }
    }
  }
}

Restart Claude Code — the atlassian server should appear in /mcp and its tools will be available as mcp__atlassian__jira_search, etc.

Claude Desktop

Add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows/Linux.

Any other MCP client

Any client that can launch an stdio MCP server can use it — point it at node /absolute/path/to/dist/index.js with the three env vars set.

Run standalone (for smoke testing)

export ATLASSIAN_SITE=your-org.atlassian.net
export ATLASSIAN_EMAIL=you@example.com
export ATLASSIAN_API_TOKEN=ATATT3x...
npm start

The server communicates over stdio, so it will look idle — that's expected. It's meant to be spawned by an MCP client, not talked to by hand. To exercise it interactively use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Tool details

Jira

Search issues via JQL. Returns a compact summary per issue plus paging info.

Args

• jql (string, required) — JQL query, e.g. project = ABC AND status = "In Progress"

• maxResults (number, 1–100, default 25)

• fields (string[], optional) — extra field names beyond the default summary set

Fetch a single issue with description and recent comments (ADF converted to text).

Args

• key (string, required) — e.g. ABC-123

• includeComments (boolean, default true)

Append a plain-text comment. The text is wrapped into a single ADF paragraph.

Args

• key (string, required)

• body (string, required)

Update editable fields. Only provided fields are changed.

Args

• key (string, required)

• summary, description, priority (strings, optional)

• assigneeAccountId (string, optional; use "unassigned" to clear)

• labels (string[], optional — replaces existing labels)

Create a new issue. Description text is converted to ADF.

Args

• projectKey (string, required), summary (string, required)

• issueType (string, default Task)

• description, assigneeAccountId, priority (strings, optional)

• labels (string[], optional)

• epicKey (string, optional) — sets Epic Link via customfield_10014 (company-managed projects)

• parentKey (string, optional) — sets parent (team-managed projects, sub-tasks)

Omit transition to list available transitions; supply it (by id or name) to apply one.

Args

• key (string, required)

• transition (string, optional)

List sprints for a Jira Software board (Agile API).

Args

• boardId (string or number, required)

• state (active | future | closed, optional)

Move issues into a sprint (Agile API).

Args

• sprintId (string or number, required)

• issueKeys (string[], required, min 1)

Confluence

Search content with CQL, e.g. space = ENG AND title ~ "onboarding".

Args

• cql (string, required)

• limit (number, 1–50, default 15)

Fetch a page by id.

Args

• pageId (string, required)

• format (text (default) | storage) — text strips HTML; storage returns raw XHTML

Create a page under a space. The body is treated as Confluence storage-format XHTML — pass HTML-like markup, not markdown. Plain text is accepted and wrapped in <p>.

Args

• spaceKey (string, required) — resolved to a spaceId internally

• title (string, required)

• body (string, required)

• parentId (string, optional)

Update a page's body (and optionally title/status). Drafts stay at version 1 per Confluence's rules; pass status: "current" to publish a draft.

Args

• pageId (string, required)

• body (string, required)

• title (string, optional)

• status (draft | current, optional)

Project layout

src/
  index.ts             # stdio entrypoint, wires the server + tools
  client.ts            # thin fetch wrapper with Basic auth + typed errors
  adf.ts               # tiny ADF <-> plain-text converter
  tools/
    jira.ts            # jira_* tool registrations
    confluence.ts      # confluence_* tool registrations

Development

npm run dev    # tsc --watch
npm run build  # compile once, chmod +x dist/index.js
npm start      # node dist/index.js (needs env vars set)

The MCP server is written against the official @modelcontextprotocol/sdk. Every tool is registered with a Zod schema — argument validation and the tool manifest come from the same source.

Security notes

• API tokens are as powerful as your account — treat them like passwords.

• The included .gitignore blocks .env; keep it that way.

• All requests go directly from the server process to your Atlassian site over HTTPS with HTTP Basic auth (email:token base64-encoded). Nothing is proxied or logged.

License

No license granted. This is a personal utility — fork it if you want to use or modify it.