JIRA MCP Server 🚀
About
# JIRA MCP Server 🚀 <!-- Badges - TODO: Replace <USER>/<REPO> and add real token/links --> [](https://github.com/karolswdev/jira-mcp-server/actions/workflows/ci.yml) [
<!-- Codecov token set via GitHub Secret: CODECOV_TOKEN -->
A flexible Go server implementing the Model Context Protocol (MCP) to interact with the JIRA Cloud REST API, enabling seamless integration between LLMs/tools and your JIRA projects.
What is this? 🤔
This project provides a bridge between systems that speak the Model Context Protocol (like certain AI assistants or development tools) and the powerful JIRA Cloud API. It allows you to perform common JIRA actions (creating issues, searching, retrieving details) programmatically through a standardized MCP interface, abstracting away the complexities of direct JIRA API calls.
✨ Features
MCP Interface: Exposes JIRA actions via standard MCP endpoints.
JIRA Cloud Integration: Create issues, search using JQL, retrieve issue details, and fetch issues within an Epic.
Flexible Configuration: Uses Viper for configuration via environment variables, config files, or defaults.
Docker Support: Ready for containerized deployment using Docker and Docker Compose.
Robust Testing: Includes comprehensive unit and integration tests.
Structured Logging: Uses slog for clear, structured logging.
Dependency Injection: Built with clean architecture principles using wire for dependency injection.
Prerequisites
Go 1.20+ (for building/running locally)
Docker & Docker Compose (optional, for containerized deployment)
A JIRA Cloud instance
A JIRA API Token associated with a user email
🚀 Getting Started
1. Clone the repository:
git clone https://github.com/karolswdev/jira-mcp-server.git # TODO: Replace with actual URL
cd jira-mcp-server # e.g., cd jira-mcp
2. Navigate to the server directory:
cd jira-mcp-server
➡️ Important: Most subsequent commands (
make ..., go run ..., docker ...) should be run from within the jira-mcp-server/ directory.
3. Configure the server: Set the required environment variables or create a config.yaml. See the Configuration section below.
4. Run the server: See the Running the Server section below.
⚙️ Configuration
Configuration is managed using Viper and loaded from the following sources in order of precedence:
1. Environment Variables: Prefixed with JIRA_MCP_ (e.g., JIRA_MCP_JIRA_URL). Highest precedence.
2. Configuration File: config.yaml (or .json, .toml) located within the jira-mcp-server/ directory. See config.yaml.example for structure and all options.
3. Defaults: Default values defined within the application code.
Required Configuration:
These values
must be provided via environment variables or the config file:JIRA_MCP_JIRA_URL: Your JIRA Cloud instance base URL (e.g., https://your-domain.atlassian.net).JIRA_MCP_JIRA_USER_EMAIL: The email address of the JIRA user associated with the API token.JIRA_MCP_JIRA_API_TOKEN: Your JIRA API token. Treat this like a password!
Optional Configuration:
JIRA_MCP_PORT: Port for the server to listen on (Default: 8080).
JIRA_MCP_LOG_LEVEL: Logging level (debug, info, warn, error) (Default: info).
-
JIRA_MCP_EPIC_LINK_FIELD_ID: The custom field ID for the "Epic Link" in your JIRA instance (e.g.,customfield_10014). Required for the/jira_epic/{epicKey}/issuesendpoint to function correctly. Find this ID via your JIRA API or administration settings.
Example (Environment Variables):
export JIRA_MCP_JIRA_URL="https://your-domain.atlassian.net"
export JIRA_MCP_JIRA_USER_EMAIL="your.email@example.com"
export JIRA_MCP_JIRA_API_TOKEN="your-api-token-secret"
export JIRA_MCP_PORT="9000" # Optional
export JIRA_MCP_EPIC_LINK_FIELD_ID="customfield_10014" # Optional but needed for Epic endpoint
▶️ Running the Server
Ensure you are inside the jira-mcp-server/ directory and have configured the required settings.
Option 1: Run Directly (using Go)
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
