🚀 Jira MCP Server: AI-Powered Issue Tracking

Transform your Jira projects into a living workspace for AI agents. This Model Context Protocol (MCP) server allows LLMs (like Gemini, Claude, and GPT-4) to see, organize, and manage your tasks and sprints with natural language.

---

🔍 Overview

This project bridges the gap between AI and your Jira workflow. Instead of manually navigating complex Jira screens, you can tell your AI: "Find all open bugs in the project and assign them to me," or "Create a new story for the login refactoring with high priority."

Global Usage: You can save this project anywhere on your computer. Once registered, your AI will be able to start the server automatically whenever needed—no manual terminal execution required.

---

📋 Prerequisites

• Node.js (v20.0.0 or higher recommended) - Download here
• Git - Download here
• Jira API Credentials: Get an API Token here

---

🛠️ Quick Start

1. Installation & Build

# Clone the repository (or copy the files)
npm install
npm run build

2. Configuration

Create a .env file in the project root (use .env.example as a template):

JIRA_EMAIL=your_email@example.com
JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=https://your-domain.atlassian.net

3. Register with Gemini CLI (Global)

To use this server anywhere on your computer, register it with the user scope:

gemini mcp add jira node "C:\FULL_PATH\TO\jira-mcp-server\dist\index.js" --scope user --trust

[!IMPORTANT] Always use the absolute path to dist/index.js in the command above.

---

⚡ Available Tools

Your AI agent will automatically "learn" these advanced capabilities:

📋 Project & Issue Management (Full CRUD)

• list_projects: List all accessible Jira projects.
• search_issues: Find issues using JQL or text queries.
• get_issue: Fetch full details of a specific Jira issue.
• create_issue / update_issue: Create or modify stories, tasks, or bugs.
• delete_issues: Bulk Action to remove multiple issues and their subtasks.
• create_subtask: Granular task breakdown for parent issues.
• link_issues / delete_issue_link: Manage relationships between issues.
• get_all_labels: List all labels used in the instance.
• add_attachment / delete_attachment: Manage file attachments.

⏱️ Time & Work Tracking

• add_worklog / update_worklog: Log and modify hours worked on a task.
• delete_worklog: Remove incorrect worklog entries.

🔄 Transitions & Workflow

• get_transitions: See available status changes for an issue.
• transition_issue: Move an issue through your workflow.

📊 Agile & Boards (Scrum/Kanban)

• get_boards: List all Scrum and Kanban boards.
• get_sprints: List sprints for a specific board.
• get_backlog: Fetch issues in the backlog.
• create_sprint / update_sprint: Manage sprint details and goals.
• update_sprint_state: Start (active) or Close (closed) a sprint.
• delete_sprints: Remove one or more sprints from a board.

📦 Releases & Versions

• get_project_versions: List all releases/versions for a project.
• create_version / update_version: Manage the release lifecycle.
• delete_versions: Remove project versions.

🚀 Bulk Operations (Granular & Optimized)

• bulk_create_issues: Create up to 50 issues in a single request.
• bulk_transition_issues: Move multiple issues to a new status at once.
• delete_issues / delete_sprints: Scalable deletion handling single or multiple IDs.

👥 Professional Features

• assign_issue: Assign teammates to tasks.
• add_comment / update_comment: Manage discussion threads.
• delete_comment: Remove irrelevant comments.
• find_users: Search for users to get their account IDs.
• get_myself: Get your own profile details.

---

🛠️ Troubleshooting

[!WARNING] Server shows as "Disconnected"?

1. Empty Command: If /mcp list shows a red dot, ensure your settings.json (at C:\Users\YourUser\.gemini\settings.json) has "command": "node" correctly set.
2. Environment Variables: Run node dist/index.js manually. If it fails, check your .env or the environment variables in your client settings.
3. SDK Compatibility: This project uses @modelcontextprotocol/sdk v1.29.0.

---

🐳 Docker Support

[!TIP] Docker is perfect for keeping your local environment clean.

# Build
docker build -t jira-mcp-server .

# Run
docker run --rm -i --env-file .env jira-mcp-server

---

🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

---

Created by [Luiz Feltrin]
Show some love! Give this repository a ⭐️ if it helped you!