README.md•4.18 kB
# Jira MCP Server
An MCP (Model Context Protocol) server that integrates with Jira, allowing ticket creation and retrieval through the REST API.
## Features
- Create Jira tickets with customizable fields
- Retrieve ticket information by ticket key
- Returns ticket number and full ticket details
- Dockerized for easy deployment
## Prerequisites
- Docker and Docker Compose
- Jira account with API token
## Getting Started
### 1. Get Jira API Token
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Copy the generated token
### 2. Configure Environment Variables
Copy the example environment file and fill in your Jira credentials:
```bash
cp .env.example .env
```
Edit `.env` with your values:
- `JIRA_BASE_URL`: Your Jira instance URL (e.g., `https://your-domain.atlassian.net`)
- `JIRA_EMAIL`: Your Jira account email
- `JIRA_API_TOKEN`: Your Jira API token
### 3. Build and Run with Docker Compose
```bash
docker-compose up --build
```
Or run in detached mode:
```bash
docker-compose up -d --build
```
### 4. Run Locally (Optional)
If you prefer to run without Docker:
```bash
pip install -r requirements.txt
export JIRA_BASE_URL=https://your-domain.atlassian.net
export JIRA_EMAIL=your-email@example.com
export JIRA_API_TOKEN=your-api-token
python server.py
```
## Available Tools
### create_jira_ticket
Creates a new Jira ticket.
**Required Parameters:**
- `project_key` (string): Jira project key (e.g., "PROJ")
- `summary` (string): Ticket summary/title
- `description` (string): Ticket description
**Optional Parameters:**
- `issue_type` (string): Type of issue (Task, Bug, Story, Epic, etc.) - Default: "Task"
- `priority` (string): Priority level (Highest, High, Medium, Low, Lowest)
- `labels` (array): List of labels to add to the ticket
- `assignee` (string): Account ID of the assignee
- `reporter` (string): Account ID of the reporter
**Response:**
```json
{
"ticket_number": "PROJ-123",
"ticket_url": "https://your-domain.atlassian.net/browse/PROJ-123",
"ticket_info": {
"key": "PROJ-123",
"summary": "Ticket Title",
"description": "Ticket description",
"status": "To Do",
"issue_type": "Task",
"priority": "Medium",
"assignee": "John Doe",
"reporter": "Jane Smith",
"created": "2024-01-01T00:00:00.000+0000",
"updated": "2024-01-01T00:00:00.000+0000",
"labels": ["label1", "label2"],
"project": "PROJ"
}
}
```
### get_jira_ticket
Retrieves information about an existing Jira ticket.
**Required Parameters:**
- `ticket_key` (string): Jira ticket key (e.g., "PROJ-123")
**Response:**
```json
{
"ticket_number": "PROJ-123",
"ticket_url": "https://your-domain.atlassian.net/browse/PROJ-123",
"ticket_info": {
"key": "PROJ-123",
"summary": "Ticket Title",
"description": "Ticket description",
"status": "In Progress",
"issue_type": "Task",
"priority": "High",
"assignee": "John Doe",
"reporter": "Jane Smith",
"created": "2024-01-01T00:00:00.000+0000",
"updated": "2024-01-02T00:00:00.000+0000",
"labels": ["label1"],
"project": "PROJ"
}
}
```
## Example Usage
### Create a Ticket
```json
{
"name": "create_jira_ticket",
"arguments": {
"project_key": "PROJ",
"summary": "Fix login bug",
"description": "Users cannot log in with email addresses containing plus signs",
"issue_type": "Bug",
"priority": "High",
"labels": ["bug", "authentication"]
}
}
```
### Get Ticket Information
```json
{
"name": "get_jira_ticket",
"arguments": {
"ticket_key": "PROJ-123"
}
}
```
## Troubleshooting
### Authentication Errors
- Verify your Jira email and API token are correct
- Ensure your Jira instance URL is correct (include `https://` and no trailing slash)
- Check that your account has permission to create tickets in the specified project
### Project Key Errors
- Ensure the project key exists in your Jira instance
- Project keys are case-sensitive
### Issue Type Errors
- Verify the issue type name matches exactly (e.g., "Task", "Bug", "Story")
- Check that the issue type is available in the specified project
## License
MIT