Content
# Personal JIRA MCP
A personal JIRA integration plugin based on the FastMCP framework, used to query JIRA issue details, lists, and perform basic operations, supporting JIRA attachment management.
## What is MCP?
MCP (Model Context Protocol) is a standardized protocol for providing context and tools to large language models (LLMs). It is referred to as the "USB-C interface of AI," providing a unified way to connect LLMs with various resources and functionalities.
This project is an MCP server specifically designed for JIRA integration, allowing AI to access JIRA data and functionalities through a standardized interface. This enables AI assistants to:
- Query and retrieve JIRA issues
- Create and update work items
- Download and manage attachments
- Perform JIRA-related operations
## Main Features
- Query JIRA issue details and lists
- Create and update JIRA issues
- Retrieve project lists and details
- Manage and download JIRA issue attachments
- Automatically save attachments to ~/.jira_mcp directory
- Subdirectory structure organized by issue ID
- Support for downloading single or all attachments
## Installation
### Prerequisites
- Python 3.10 or higher
- Install uv (recommended) or pip
### Install uv
uv is a fast Python package manager recommended for installing and managing Python packages.
#### Linux / macOS
```bash
# Install using curl
curl -sSf https://astral.sh/uv/install.sh | sh
# Or install using pip
pip install uv
```
#### Windows
```bash
# Install using PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or install using pip
pip install uv
```
#### Verify Installation
```bash
uv --version
```
### Install from PyPI
```bash
# Using uv (recommended)
uv pip install personal-jira-mcp
# Or using pip
pip install personal-jira-mcp
```
### Install from GitHub
```bash
# Using uv (recommended)
uv pip install git+https://github.com/yuezheng2006/mcp-server-jira.git
# Or using pip
pip install git+https://github.com/yuezheng2006/mcp-server-jira.git
```
### Local Development Installation
```bash
# Clone the repository
git clone https://github.com/yuezheng2006/mcp-server-jira.git
cd mcp-server-jira
# Install dependencies and install in development mode using uv
uv pip install -e .
# Or using pip
pip install -e .
```
## Configuration
Create a `.env` file and set the following environment variables:
```
JIRA_SERVER_URL=http://your-jira-instance.com
JIRA_USERNAME=your_username
JIRA_PASSWORD=your_password
# Or use API token
JIRA_API_TOKEN=your_api_token
```
### Cursor Configuration
Add the following configuration to `.cursor/mcp.json` (recommended to use uvx):
```json
{
"mcpServers": {
"personal-jira-mcp": {
"command": "uvx",
"args": [
"--from=personal-jira-mcp",
"personal-jira-mcp",
"--transport",
"stdio"
],
"env": {
"JIRA_SERVER_URL": "http://your-jira-instance.com",
"JIRA_USERNAME": "your_username",
"JIRA_PASSWORD": "your_password"
}
}
}
}
```
If you have locally installed personal-jira-mcp (not recommended), you can directly use the command:
```json
{
"mcpServers": {
"personal-jira-mcp": {
"command": "personal-jira-mcp",
"args": ["--transport", "stdio"],
"env": {
"JIRA_SERVER_URL": "http://your-jira-instance.com",
"JIRA_USERNAME": "your_username",
"JIRA_PASSWORD": "your_password"
}
}
}
}
```
### Other MCP Client Configurations
If you use other MCP protocol-supported clients or IDEs, you can use the following two methods to configure:
#### Command Line Mode
```json
{
"command": "personal-jira-mcp",
"args": ["--transport", "stdio"],
"env": {
"JIRA_SERVER_URL": "http://your-jira-instance.com",
"JIRA_USERNAME": "your_username",
"JIRA_PASSWORD": "your_password"
}
}
```
#### HTTP Mode (requires running the server separately)
```json
{
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your_token_if_needed"
}
}
```
## Quick Start
### Start MCP Server
```bash
# Use stdio transport mode (default, suitable for IDE integration)
personal-jira-mcp --transport stdio
# Use sse transport mode (suitable for web integration)
personal-jira-mcp --transport sse
# Use streamable-http mode (suitable for HTTP calls)
personal-jira-mcp --transport streamable-http --port 8000
```
### Command Line Tool
```bash
# Download a single attachment
personal-jira-extract ERP-161 example.png --output saved_file.png
# Download all attachments of an issue
personal-jira-attachments ERP-161
# List all attachments of an issue without downloading
personal-jira-attachments ERP-161 --list-only
# Output attachment information to a JSON file
personal-jira-attachments ERP-161 --output attachments.json
```
### Use in Cursor
After configuring mcp.json, you can use the following natural language commands in Cursor:
```
View JIRA issue ERP-161 details
```
```
Download all attachments of JIRA issue ERP-161
```
```
Search for all JIRA issues in the "In Progress" state
```
## Detailed Documentation
For more detailed usage guides and API references, please see [User Guide](./mcp.md).
## Tools Provided by MCP
This MCP server provides the following tools:
| Tool Name | Description | Example |
|---------|------|------|
| get_issue | Get JIRA issue details | `ERP-123` |
| search_issues | Search JIRA issue lists | `project = ERP AND status = "In Progress"` |
| create_issue | Create a JIRA issue | Create a task with the title "Fix login issue" |
| update_issue | Update a JIRA issue | Change the status of ERP-123 to "Completed" |
| get_projects | Get JIRA project lists | List all accessible projects |
| get_project | Get project details | Get detailed information about the ERP project |
| get_issue_attachments | Get all attachments of an issue | List all attachments of ERP-123 |
| download_all_attachments | Download all attachments of an issue | Download all attachments of ERP-123 |
| get_attachment_by_filename | Get a specific attachment | Get the attachment named "screenshot.png" from ERP-123 |
## Development
### Install Development Dependencies
```bash
# Using uv
uv pip install -e ".[dev]"
# Or using pip
pip install -e ".[dev]"
```
## Release
### Use Automated Script for Release
```bash
# Use the included release script
./scripts/publish.sh
```
### Manually Build and Release to PyPI
```bash
# Ensure build tools are installed
pip install build twine
# Build the package
python -m build
# Upload to PyPI
python -m twine upload dist/*
```
## License
MIT
