Jira MCP Scoped

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:

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

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": "[email protected]",
        "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": "[email protected]",
        "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"
    }
  }
}