# 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`](https://www.npmjs.com/package/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:

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

## Testing

```bash
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](https://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](#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.

```json
{
  "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):

```json
{
  "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:

```bash
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:

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