Jira MCP Server

An MCP (Model Context Protocol) server that lets AI assistants interact with Jira — scoped to a single project (JIRA_PROJECT_KEY) instead of everything your account can access.

Published on npm as jira-mcp-scoped — run it with npx -y jira-mcp-scoped, no clone or install required.

The server ships in two transports:

• stdio (mcpOverStdio.js) — the default for local clients (Claude Desktop, Claude Code, Copilot in VS Code). The client spawns the Node process directly.
• HTTP (mcpOverHttp.js) — exposes the same tools over a Streamable HTTP endpoint at /mcp (default port 3456). Useful if you want to start the MCP as a stand alone service (e.g in docker) and provide credentials on startup, making them invisible to the AI agent

Both transports share the same tool implementations in toolDefinitions.js and jiraRestService.js.

Logging

The server logs to stderr (so it never corrupts the stdio protocol on stdout). The verbosity is controlled by the JIRA_LOG_LEVEL env var:

Level	What it logs
error	Failures only — failed tool calls and request errors.
info	(default) Startup config and one line per tool call (name + arguments). Plus everything error logs.
debug	Per-request Jira API traffic (→/← with method, path, status), tool result previews, and HTTP session lifecycle. Plus everything info logs.

Long string arguments (e.g. description, comment) are collapsed to a <string: N chars> placeholder so the logs stay readable. The Jira API token is never logged. Each line is formatted as <ISO timestamp> [jira-mcp] <LEVEL> <message>.

Prerequisites

• Node.js 20+
• A Jira account with API access

Installation

No installation needed — MCP clients can run the published package directly via npx (see the setup sections below).

For local development:

git clone https://github.com/MichalOsadowski/jira-mcp.git
cd jira-mcp
npm install

Testing

npm test

Runs the node:test suite (*.test.js) with the Jira HTTP layer stubbed — no network access or credentials required.

Environment variables

Variable	Required	Description
JIRA_BASE_URL	Yes	Your Jira instance URL, e.g. https://yourcompany.atlassian.net
JIRA_USER_EMAIL	Yes	The email address of your Jira account
JIRA_API_TOKEN	Yes	Jira API token — generate one at id.atlassian.com/manage-profile/security/api-tokens
JIRA_PROJECT_KEY	Yes	The project key, e.g. PROJ
JIRA_BOARD_ID	No	Board ID used when placing issues in the current sprint
JIRA_ATTACHMENTS_DIR	No	Directory to save downloaded attachments (default: ./jira-attachments)
JIRA_LOG_LEVEL	No	Log verbosity: error, info (default), or debug. See Logging.

Setup for Claude Code

Add the server to your Claude Code MCP configuration. For a repository specific setup add .mcp.json in the root of your repository.

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-scoped"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USER_EMAIL": "you@yourcompany.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_PROJECT_KEY": "PROJ",
        "JIRA_BOARD_ID": "1"
      }
    }
  }
}

Restart Claude Code after saving. You can verify the server is connected by running /mcp in the Claude Code CLI.

---

Setup for GitHub Copilot (VS Code)

Add the server to .vscode/mcp.json in the repository root (create it if it doesn't exist):

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jira-mcp-scoped"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_USER_EMAIL": "you@yourcompany.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_PROJECT_KEY": "PROJ",
        "JIRA_BOARD_ID": "1"
      }
    }
  }
}

Note: Do not commit .vscode/mcp.json if it contains your API token. Add it to .gitignore or use VS Code's user-level settings instead (~/.config/Code/User/settings.json) under github.copilot.mcp.servers.

Reload the VS Code window after saving. The Jira tools will appear in the Copilot agent tool list.

---

Running the HTTP transport

The HTTP variant is useful when the MCP client cannot spawn a local Node process — e.g. when running Claude inside a container, or pointing a remote agent at a long-lived server.

Run it directly from the cloned repository:

JIRA_BASE_URL=... JIRA_USER_EMAIL=... JIRA_API_TOKEN=... JIRA_PROJECT_KEY=PROJ JIRA_BOARD_ID=1 \
  npm run start:http

The server listens on http://localhost:3456/mcp (override with PORT) and exposes a /health endpoint. Environment variables are the same as the stdio transport.

Point an HTTP-capable MCP client at it:

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "http://localhost:3456/mcp"
    }
  }
}