Provides integration with Jira Cloud, enabling AI agents to search for issues using JQL, retrieve detailed issue information including comments and attachments, create new issues, and download attachments.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Simple Jira MCPsearch for all open bugs assigned to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Simple Jira MCP
A Model Context Protocol (MCP) server that provides Jira Cloud integration for AI agents.
Features
Search issues using JQL (Jira Query Language)
Retrieve issue details with comments and attachments
Create new issues
Download attachments
Support for multiple Jira configurations
Requirements
Python 3.11+
Jira Cloud account with API token
Installation
git clone https://github.com/yourusername/simple-jira-mcp.git
cd simple-jira-mcp
python -m venv venv
# Linux/macOS
source venv/bin/activate
# Windows
# venv\Scripts\activate
pip install -e ".[dev]"Configuration
Set the JIRA_CONFIG_JSON environment variable with your Jira credentials:
export JIRA_CONFIG_JSON='[
{
"id": "work",
"url": "https://your-domain.atlassian.net",
"email": "your-email@example.com",
"token": "your-api-token"
}
]'Generate an API token at: https://id.atlassian.com/manage-profile/security/api-tokens
AI Tool Integration
Claude Desktop
Platform | Config Path |
macOS |
|
Linux |
|
Windows |
|
{
"mcpServers": {
"jira": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/simple-jira-mcp",
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Claude Code (CLI)
Edit ~/.claude.json:
{
"mcpServers": {
"jira": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/simple-jira-mcp",
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Verify with claude mcp list.
Gemini CLI
Config file: ~/.gemini/settings.json
{
"mcpServers": {
"jira": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/simple-jira-mcp",
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Verify with /mcp command in Gemini CLI.
OpenAI Codex CLI
Config file: ~/.codex/config.toml
[mcp_servers.jira]
command = "python"
args = ["-m", "src"]
cwd = "/path/to/simple-jira-mcp"
[mcp_servers.jira.env]
JIRA_CONFIG_JSON = '[{"id": "work", "url": "https://your-domain.atlassian.net", "email": "your-email@example.com", "token": "your-api-token"}]'Cursor
Scope | Config Path |
Global |
|
Project |
|
{
"mcpServers": {
"jira": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/simple-jira-mcp",
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Access via Cursor Settings > MCP.
Windsurf (Codeium)
Platform | Config Path |
macOS/Linux |
|
Windows |
|
{
"mcpServers": {
"jira": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/simple-jira-mcp",
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Access via Windsurf Settings > Cascade > Plugins (MCP servers).
VS Code with GitHub Copilot
Config file: .vscode/mcp.json (project-level)
{
"servers": {
"jira": {
"command": "python",
"args": ["-m", "src"],
"cwd": "/path/to/simple-jira-mcp",
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Requires VS Code 1.102+ with GitHub Copilot. Use Agent Mode in Copilot Chat.
Zed
Add to Zed settings.json:
{
"context_servers": {
"jira": {
"source": "custom",
"command": "python",
"args": ["-m", "src"],
"env": {
"JIRA_CONFIG_JSON": "[{\"id\": \"work\", \"url\": \"https://your-domain.atlassian.net\", \"email\": \"your-email@example.com\", \"token\": \"your-api-token\"}]"
}
}
}
}Note: Run Zed from the project folder or use the full path to the Python executable in the venv.
Windows Notes
On Windows, use full paths with backslashes:
{
"command": "C:\\path\\to\\simple-jira-mcp\\venv\\Scripts\\python.exe",
"cwd": "C:\\path\\to\\simple-jira-mcp"
}Available Tools
Tool | Description |
| List available Jira configurations |
| Search issues using JQL |
| Get detailed issue information |
| Create a new issue |
| Download an attachment from an issue |
Usage Notes
list_configs: Returns configs withdefaulttrue for the first entry inJIRA_CONFIG_JSON.search_issues: JQL must include at least one bounding filter; semicolons and newlines are rejected. Supports cursor pagination withnext_page_token. Thefieldsallowlist is forwarded to Jira to limit fetched data, but responses stay normalized to key, summary, status, assignee, priority, issue_type, labels, created, updated, url.get_issue:include_commentsandinclude_attachmentstoggle those sections. Descriptions and comments are plain text; attachments includesize_kbandmime_type.create_issue: Summary max 255 characters; description is converted to ADF; optionalpriority,labels, andassignee_account_id.download_attachment:output_dirmust exist when provided; files are saved to<output_dir>/<issue_key>/with sanitized filenames.
Reference
See API_REFERENCE.md for tool inputs/outputs, error codes, and JQL patterns.
Development
# Run all checks (lint, type check, tests)
./check.sh
# Run specific checks
./check.sh -l # Linting only
./check.sh -m # Type checking only
./check.sh -t # Tests only
./check.sh -c # Tests with coverage
./check.sh -f # Auto-fix linting issuesLicense
MIT License - see LICENSE for details.