Jira MCP Server

A Model Context Protocol (MCP) server for self-hosted Jira instances using Personal Access Token (PAT) authentication.

✨ Features

• Smart field handling: values are matched against each field's real selectable options (dropdowns, multi-selects, cascading selects, versions, components, priorities) before anything is sent to Jira. Harmless differences (case, spacing, unique partial names) are fixed; ambiguous or invalid values are never guessed.

• Asks instead of failing: on clients that support MCP elicitation, ambiguous values, unknown projects and missing required fields are put to the user as choices. Other clients get the valid options in the error so the model can ask.

• Project discovery: a project key that does not exist (renamed, split or retired) returns the closest live projects instead of a blind failure.

• Duplicate-safe create: timeouts and dropped connections are not retried blindly; the server looks for the ticket it may have created. The response reports the real key/project (Jira automation can move tickets).

• Workflow-aware transitions: transitions by name, with required transition-screen fields (resolution, assignee, comment) resolved against their real options.

• Works across Jira versions: create metadata falls back from the paged endpoint to the legacy endpoint to edit metadata.

• Current MCP: built on the v2 TypeScript SDK. One server serves both the 2025 and the 2026-07-28 protocol revisions (see MCP features).

• Issues, JQL search, comments, projects, users, watchers and links.

Related MCP server: Jira MCP Server

📋 Prerequisites

• Node.js 20+

• Self-hosted Jira Server / Data Center (tested with 9.x and 10.x)

• Personal Access Token (PAT) for authentication

🚀 Installation

npm install
npm run build

⚙️ Configuration

Create a .env file in the project root:

JIRA_BASE_URL=https://your-jira-instance.com/
PAT=your-personal-access-token

Getting a Personal Access Token

1. Log in to your Jira instance

2. Go to Profile → Personal Access Tokens

3. Create a new token with appropriate permissions

4. Copy the token to your .env file

📖 Usage

Running the Server

npm start

Development Mode

npm run dev

Using with npx (Recommended)

No installation required! Add the following to your MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-server-pro"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com/",
        "PAT": "your-personal-access-token"
      }
    }
  }
}

Global Installation

npm install -g jira-mcp-server-pro

Then add to your MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server-pro",
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com/",
        "PAT": "your-personal-access-token"
      }
    }
  }
}

Local Development

If running from source, add the following to your MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jiraMCP/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com/",
        "PAT": "your-personal-access-token"
      }
    }
  }
}

🛠️ Available Tools (29)

All tools carry MCP annotations (read-only / destructive / idempotent hints) and a human-readable title.

Smart create, update and transition

Discovery

Issues and comments

🔌 MCP features

Deliberately not used: MCP logging, sampling and roots are deprecated in the 2026-07-28 revision (diagnostics go to stderr instead). Tasks and HTTP transports are not needed for a local stdio server where every operation is short; adding an HTTP transport would expose a token-backed server on the network, so it is intentionally left out.

🧠 How value resolution works

For every field you pass, the server reads Jira's metadata for that project/issue type (or the issue, when updating) and:

1. finds the field by id or display name,

2. matches the value to the field's options by id, exact label, normalized label, then unique prefix/substring,

3. shapes it correctly ({id} for selects, arrays for multi-selects, {id, child:{id}} for cascading selects, {name} for users),

4. for anything ambiguous or invalid, asks the user (elicitation) or returns the closest valid options,

5. asks for required fields that were not provided.

Cascading selects accept "Parent > Child". Use dryRun: true to preview the exact payload.

📝 Workflow: creating issues

jira_create_issue_advanced(
  projectKey: "PROJ",
  issueType: "bug",              // matched to "Bug"
  summary: "Login fails",
  priority: "high",              // matched to the real priority name
  customFields: { "Environment": "staging" },
  dryRun: true
)

Review the returned payload, then call again without dryRun.

💬 Prompts

Prompt arguments such as project support autocompletion.

📚 Resources

🔍 Example JQL Queries

# Issues assigned to me
assignee = currentUser()

# Open bugs in a project
project = PROJ AND issuetype = Bug AND status != Done

# Issues created in the last 7 days
created >= -7d

# High priority issues
priority in (Highest, High)

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/yogeshhrathod/jiraMCP.git
cd jiraMCP

# Install dependencies
npm install

# Run in development mode
npm run dev

Reporting Issues

• Use the GitHub Issues to report bugs

• Include your Node.js version, Jira version, and steps to reproduce

• Check existing issues before creating a new one

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the MCP specification

• Atlassian for Jira REST API documentation

🐞 Repeated failures and bug reports

If a tool fails twice with the same error, or fails with an unexpected server error, the response tells the AI to stop retrying and suggest a GitHub issue. jira_report_issue then prepares a draft with the tool name, redacted error, and versions, plus a prefilled link. Tokens, hostnames, emails, ticket keys and quoted values are stripped, and nothing is submitted until the user opens the link.

🔒 Security

Credentials are read only from the JIRA_BASE_URL and PAT environment variables (or a local .env, which is git-ignored). Nothing is logged or returned that contains the token. Keep tokens out of committed MCP client configs, and rotate any token that was ever committed or shared.

Optional: JIRA_REQUEST_TIMEOUT_MS (default 120000).

🧪 Tests

npm test

Unit tests cover option matching and redaction. Integration tests start the real server over stdio against a fake Jira and run each scenario on both protocol eras, including multi-round elicitation.

📦 MCP Registry

The repository ships server.json and mcpName so the package can be listed in the official MCP Registry (mcp-publisher login github && mcp-publisher publish, after the npm release).