Content
# Personal JIRA MCP
A personal JIRA integration plugin based on the FastMCP framework, used for querying JIRA issue details, lists, and performing basic operations, supporting JIRA attachment management.
## What is MCP?
MCP (Model Context Protocol) is a standardized protocol that provides context and tools for large language models (LLM). It is referred to as the "USB-C interface for AI," offering 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, enabling AI assistants to:
- Query and retrieve JIRA issues
- Create and update work items
- Download and manage attachments
- Perform JIRA-related operations
## Key Features
- Query JIRA issue details and issue lists
- Create and update JIRA issues
- Retrieve project lists and details
- Manage and download JIRA issue attachments
- Automatically save attachments to the ~/.jira_mcp directory
- Organize in a subdirectory structure by issue ID
- Support downloading individual 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 set up 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 in `.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 already installed personal-jira-mcp locally (not recommended), you can also use the command directly:
```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 are using other clients or IDEs that support the MCP protocol, you can configure them in the following two ways:
#### Command Line Based
```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 Based (requires running the server separately)
```json
{
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your_token_if_needed"
}
}
```
## Quick Start
### Start the MCP Server
```bash
# Using stdio transport mode (default, suitable for IDE integration)
personal-jira-mcp --transport stdio
# Using sse transport mode (suitable for web integration)
personal-jira-mcp --transport sse
# Using streamable-http mode (suitable for HTTP calls)
personal-jira-mcp --transport streamable-http --port 8000
```
### Command Line Tools
```bash
# Download a single attachment
personal-jira-extract ERP-161 example.png --output saved_file.png
# Download all attachments for an issue
personal-jira-attachments ERP-161
# List all attachments for 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
```
### Using in Cursor
After configuring mcp.json, you can use the following natural language commands in Cursor:
```
View details of JIRA issue ERP-161
```
```
Download all attachments for JIRA issue ERP-161
```
```
Search for all JIRA issues in "In Progress" status
```
## Detailed Documentation
For more detailed usage guides and API references, please refer to the [Usage 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 list | `project = ERP AND status = "In Progress"` |
| create_issue | Create a JIRA issue | Create a task titled "Fix login issue" |
| update_issue | Update a JIRA issue | Change the status of ERP-123 to "Done" |
| get_projects | Get JIRA project list | List all accessible projects |
| get_project | Get project details | Get detailed information about the ERP project |
| get_issue_attachments | Get all attachments for an issue | List all attachments for ERP-123 |
| download_all_attachments | Download all attachments for an issue | Download all attachments for 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
### Release Using Automation Script
```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
