<p align="center">
  <img src="assets/logo.svg" alt="Jira MCP Server logo" width="480" />
</p>

<p align="center">
  A lightweight <a href="https://modelcontextprotocol.io">Model Context Protocol (MCP)</a> server that exposes Jira issue operations as tools for MCP-compatible AI clients (Claude Desktop, Claude Code, etc.).
</p>

<p align="center">
  <img alt="Node.js" src="https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white" />
  <img alt="License" src="https://img.shields.io/badge/license-ISC-blue" />
  <img alt="MCP" src="https://img.shields.io/badge/MCP-stdio-6E56CF" />
</p>

---

## Overview

`jira-mcp-server` runs as a local stdio-based MCP server. It connects to a Jira Cloud instance via the REST API and exposes three tools that an MCP client can call: fetching an issue, searching issues with JQL, and creating new issues.

## Features

- 🔍 **Get issue** — fetch a single Jira issue by key
- 🔎 **Search issues** — run arbitrary JQL queries
- ➕ **Create issue** — create a new issue in a project
- 🔌 Implements the MCP `tools/list` and `tools/call` protocol over stdio
- ⚙️ Configuration via environment variables (`.env`)

## Prerequisites

- [Node.js](https://nodejs.org/) 18 or later
- A Jira Cloud site and an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens)
- An MCP-compatible client (e.g. [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.claude.com/en/docs/claude-code))

## Installation

```bash
git clone <this-repo-url>
cd jira-mcp-server
npm install
```

## Configuration

Copy the example environment file and fill in your Jira credentials:

```bash
cp .env.example .env
```

| Variable          | Description                                                         | Example                                                |
| ----------------- | --------------------------------------------------------------------| ------------------------------------------------------- |
| `JIRA_EMAIL`      | The email address associated with your Atlassian account            | `you@example.com`                                       |
| `JIRA_API_TOKEN`  | An Atlassian API token generated from your account security settings| `abcd1234...`                                            |
| `JIRA_BASE_URL`   | The base REST API URL for your Jira site                            | `https://your-domain.atlassian.net/rest/api/3`           |

> **Never commit your `.env` file.** It is already excluded via `.gitignore`.

## Running the server

```bash
node src/server.js
```

The server communicates over stdio, so it's designed to be launched by an MCP client rather than run standalone in a terminal for interactive use.

### Connecting from Claude Desktop

Add an entry to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\path\\to\\jira-mcp-server\\src\\server.js"],
      "env": {
        "JIRA_EMAIL": "you@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_BASE_URL": "https://your-domain.atlassian.net/rest/api/3"
      }
    }
  }
}
```

Restart Claude Desktop and the `jira` tools will become available in the tool picker.

## Available tools

| Tool            | Description                     | Parameters                                                                 |
| --------------- | -------------------------------- | --------------------------------------------------------------------------- |
| `get_issue`     | Get a Jira issue by key          | `key` (string, required) — e.g. `PROJ-123`                                  |
| `search_issues` | Search Jira issues using JQL     | `jql` (string, required) — a valid JQL query string                         |
| `create_issue`  | Create a new Jira issue          | `projectKey` (string, required), `summary` (string, required), `description` (string, optional) |

## Project structure

```
jira-mcp-server/
├── assets/
│   └── logo.svg          # Project logo
├── src/
│   ├── server.js         # MCP server entry point (tool routing)
│   ├── tools.js          # Tool definitions / input schemas
│   └── jiraclient.js     # Jira REST API client
├── .env.example           # Sample environment configuration
├── package.json
└── README.md
```

## Troubleshooting

- **401 Unauthorized** — verify `JIRA_EMAIL` and `JIRA_API_TOKEN` are correct and that the token hasn't expired.
- **404 Not Found** — check that `JIRA_BASE_URL` points to the correct Jira Cloud REST API base (`/rest/api/3`).
- **No output from the server** — the server communicates over stdio; run it via an MCP client rather than expecting interactive terminal output.

## License

Distributed under the [ISC License](LICENSE).