JIRA MCP Server

# JIRA MCP Server ## Security Wanning This repository contains security training materials and proof-of-concept code designed for educational purposes only. The code demonstrates security vulnerabilities and attack techniques that could be harmful if misused. Malicious sample code is in `./malicious_code_examples` **AUTHORIZED USE ONLY**: This code is provided exclusively for: - Security research and education - Authorized penetration testing with explicit written permission - Security awareness training in controlled environments - Academic study of cybersecurity concepts **PROHIBITED USES**: This code must NOT be used for: - Unauthorized access to computer systems - Malicious attacks against any systems or networks - Any illegal activities or violations of computer crime laws - Testing against systems without explicit written authorization > By downloading, viewing, or using any code in this repository, you agree to use it only for lawful, authorized purposes and accept full responsibility for your actions. ## Disclaimer of Liability The author(s) and contributors to this repository: - Provide this code "AS IS" without warranty of any kind - Disclaim all liability for any damages resulting from use or misuse - Do not endorse or encourage any illegal or unauthorized activities - Assume no responsibility for actions taken by users of this code ## Overview A Model Context Protocol (MCP) server that provides JIRA integration. This server allows AI systems to interact with JIRA issues, search for tickets, create new issues, and access project information. > Examples here will use claude. ## Features - **Get JIRA Issues**: Retrieve detailed information about specific JIRA issues - **Create Issues**: Create new JIRA issues with customizable fields - **Search Issues**: Search for JIRA issues using JQL (JIRA Query Language) - **Project Information**: Access project keys and user information - **Resources**: Access JIRA project keys and current user information ## Prerequisites - Python 3.13 or higher - JIRA account with API access - JIRA Personal Access Token (PAT) ## Installation 1. Clone or download this repository: ```bash git clone <repository-url> cd longcon-mcp-demo ``` 2. Install dependencies using uv (recommended) or pip: ```bash # Using uv (recommended) uv sync # Or using pip pip install -r requirements.txt ``` ## Configuration ### 1. JIRA Setup 1. Create a JIRA Personal Access Token: - Go to your JIRA instance - Navigate to Account Settings > Security > API tokens - Create a new token and copy it 2. Create a `.env` file in the project root: ```bash JIRA_USERNAME=your-email@example.com JIRA_PAT=your-personal-access-token JIRA_URL=https://your-instance.atlassian.net ``` 4. Update the project keys in the `jira_project_keys()` function (line 24): ```python return ['YOUR_PROJECT_KEY'] # Replace with your actual project keys ``` ### 2. Test the Server Run the server locally to ensure it's working: ```bash python main.py ``` The server should start without errors. Press Ctrl+C to stop it. ## Claude Desktop Configuration ### 1. Install Claude Desktop Download and install Claude Desktop from [https://claude.ai/download](https://claude.ai/download) ### 2. Configure MCP Server 1. Locate your Claude Desktop configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` 2. Add the MCP server configuration to the file. If the file doesn't exist, create it: ```json { "mcpServers": { "longcon": { "command": "python", "args": ["/absolute/path/to/longcon-mcp-demo/main.py"], "env": { "JIRA_USERNAME": "your-email@example.com", "JIRA_PAT": "your-personal-access-token" } } } } ``` **Important**: Replace `/absolute/path/to/longcon-mcp-demo/main.py` with the actual absolute path to your `main.py` file. ### 3. Alternative Configuration (Using .env file) If you prefer to use the `.env` file for credentials: ```json { "mcpServers": { "longcon": { "command": "python", "args": ["/absolute/path/to/longcon-mcp-demo/main.py"], "cwd": "/absolute/path/to/longcon-mcp-demo" } } } ``` ### 4. Using uv (Recommended) For better dependency management, you can use uv: ```json { "mcpServers": { "longcon": { "command": "uv", "args": ["run", "python", "main.py"], "cwd": "/absolute/path/to/longcon-mcp-demo", "env": { "JIRA_USERNAME": "your-email@example.com", "JIRA_PAT": "your-personal-access-token" } } } } ``` ## Usage in Claude Once configured, restart Claude Desktop. You can now use JIRA-related commands in your conversations: ### Available Tools 1. **Get JIRA Issue**: ``` Get details for issue CRM-123 ``` 2. **Create JIRA Issue**: ``` Create a new task in project CRM with summary "Fix login bug" and description "Users unable to login" ``` 3. **Search JIRA Issues**: ``` Search for all open issues assigned to me ``` ### Available Resources - **Project Keys**: Access available project keys - **User Information**: Get current user details ### Example Interactions ``` User: What are the details of issue CRM-123? Claude: [Uses get_jira_issue tool to fetch and display issue details] User: Create a bug report for the login issue Claude: [Uses create_jira_issue tool to create a new issue] User: Show me all high-priority open issues Claude: [Uses search_jira_issues with JQL: "priority = High AND status = Open"] ``` ## Troubleshooting ### Common Issues 1. **"JIRA_USERNAME and JIRA_PAT must be set" Error** - Ensure your `.env` file is in the correct location - Verify the environment variables are set correctly in Claude Desktop config 2. **"Permission Denied" Error** - Check that your JIRA PAT has the necessary permissions - Verify your JIRA username is correct 3. **"Server not found" Error** - Ensure the JIRA server URL is correct in `main.py` - Check your internet connection 4. **Claude Desktop doesn't recognize the server** - Verify the absolute path in the configuration is correct - Restart Claude Desktop after making configuration changes - Check Claude Desktop logs for error messages ### Verification To verify everything is working: 1. Start a new conversation in Claude Desktop 2. Ask: "What JIRA projects are available?" 3. Claude should respond with the project keys you configured ### Dependencies - `jira`: JIRA Python library for API interactions - `fastmcp`: Simplified MCP server framework - `python-dotenv`: Environment variable management ## Security Notes - Never commit your `.env` file or expose your JIRA PAT - Use environment variables or secure configuration management - Regularly rotate your JIRA Personal Access Tokens - Limit PAT permissions to only what's necessary