Jira MCP Server

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

✨ Features

• Issue Management: Get, create, update, delete, and assign issues
• Search: Search issues using JQL
• Comments: Get, add, update, and delete comments
• Transitions: Get available transitions and transition issues
• Projects: List and get project details
• Users: Search users and get current user
• Watchers: Add watchers to issues
• Issue Links: Link issues together

📋 Prerequisites

• Node.js 18+
• Self-hosted Jira instance (tested with v9.12.12)
• 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 (27 total)

Issue Operations

Comments

Projects

Metadata & Field Discovery

Users

📝 Workflow: Creating Issues with Required Fields

1. First, call jira_get_create_meta to discover required fields and allowed values:

   jira_get_create_meta(projectKey: "PROJ", issueType: "Bug")
   

   This returns all fields with their requirements and dropdown options.

2. Then, use jira_create_issue_advanced with the correct values:

   jira_create_issue_advanced(
     projectKey: "PROJ",
     summary: "Issue title",
     issueType: "Bug",
     fixVersions: ["1.0.0"],
     components: ["Backend"],
     customFields: {"customfield_10001": "value"}
   )
   

📚 Resources

The server exposes MCP Resources for quick access to Jira data without tool calls:

Using Resources

Resources provide context without explicit tool calls. For example, reading jira://project/MSSP returns:

{
  "key": "MSSP",
  "name": "MSSP",
  "versions": [{"name": "1.0.0", "released": true}, ...],
  "components": [{"name": "LOGIN"}, {"name": "MSSP-FO"}, ...],
  "issueTypes": [{"id": "1", "name": "Bug"}, {"id": "3", "name": "Task"}, ...]
}

🔍 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/YOUR_USERNAME/jira-mcp-server.git
cd jira-mcp-server

# 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

Made with ❤️ for the MCP community