JIRA MCP Server
A Model Context Protocol (MCP) server implementation that provides access to JIRA data with relationship tracking, optimized data payloads, and data cleaning for AI context windows.
ℹ️ There is a separate MCP server for Confluence
Jira Cloud & Jira Server (Data Center) Support
This MCP server supports both Jira Cloud and Jira Server (Data Center) instances. You can select which type to use by setting the JIRA_TYPE environment variable:
cloud(default): For Jira Cloud (Atlassian-hosted)server: For Jira Server/Data Center (self-hosted)
The server will automatically use the correct API version and authentication method for the selected type.
Features
- Search JIRA issues using JQL (maximum 50 results per request)
- Retrieve epic children with comment history and optimized payloads (maximum 100 issues per request)
- Get detailed issue information including comments and related issues
- Create, update, and manage JIRA issues
- Add comments to issues
- Extract issue mentions from Atlassian Document Format
- Track issue relationships (mentions, links, parent/child, epics)
- Clean and transform rich JIRA content for AI context efficiency
- Support for file attachments with secure multipart upload handling
- Supports both Jira Cloud and Jira Server (Data Center) APIs
- Dual transport modes: STDIO (default) and Streamable HTTP (MCP 2025-03-26) for tools like Postman and MCP Inspector
Prerequisites
- Bun (v1.0.0 or higher)
- JIRA account with API access
Environment Variables
JIRA_API_TOKEN=your_api_token # API token for Cloud, PAT or password for Server/DC
JIRA_BASE_URL=your_jira_instance_url # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email # Your Jira account email
JIRA_TYPE=cloud # 'cloud' or 'server' (optional, defaults to 'cloud')
JIRA_AUTH_TYPE=basic # 'basic' or 'bearer' (optional, defaults to 'basic')
TRANSPORT_MODE=stdio # 'stdio' or 'http' (optional, defaults to 'stdio')
HTTP_PORT=3000 # Port for HTTP transport (optional, defaults to 3000)
Authentication Methods
-
Jira Cloud: Use API tokens with Basic authentication
- Create an API token at: https://id.atlassian.com/manage-profile/security/api-tokens
- Set
JIRA_AUTH_TYPE=basic(default)
-
Jira Server/Data Center:
- Basic Auth: Use username/password or API tokens
- Set
JIRA_AUTH_TYPE=basic(default)
- Set
- Bearer Auth: Use Personal Access Tokens (PATs) - available in Data Center 8.14.0+
- Create a PAT in your profile settings
- Set
JIRA_AUTH_TYPE=bearer - Use the PAT as your
JIRA_API_TOKEN
- Basic Auth: Use username/password or API tokens
Installation & Setup
1. Clone the repository
git clone [repository-url]
cd jira-mcp
2. Install dependencies and build
bun install
bun run build
3. Configure the MCP server
The server supports two transport modes: STDIO (default, for Claude Desktop/Cline) and HTTP (for Postman and other HTTP-based clients).
Option A: STDIO Transport (Default - Claude Desktop/Cline)
Edit the appropriate configuration file:
macOS:
- Cline:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
- Cline:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json - Claude Desktop:
%APPDATA%\Claude Desktop\claude_desktop_config.json
Linux:
- Cline:
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - Claude Desktop: sadly doesn't exist yet
Add the following configuration under the mcpServers object:
{
"mcpServers": {
"jira": {
"command": "node",
"args": ["/absolute/path/to/jira-mcp/build/index.js"],
"env": {
"JIRA_API_TOKEN": "your_api_token",
"JIRA_BASE_URL": "your_jira_instance_url",
"JIRA_USER_EMAIL": "your_email",
"JIRA_TYPE": "cloud",
"JIRA_AUTH_TYPE": "basic"
}
}
}
}
Option B: Streamable HTTP Transport (MCP Inspector & Postman)
- Start the server in HTTP mode:
# Set environment variables
export JIRA_API_TOKEN="your_api_token"
export JIRA_BASE_URL="your_jira_instance_url"
export JIRA_USER_EMAIL="your_email"
export TRANSPORT_MODE="http"
export HTTP_PORT="3000" # optional, defaults to 3000
# Run the server
bun run build/index.js
Or use a .env file:
# .env
JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=your_jira_instance_url
JIRA_USER_EMAIL=your_email
JIRA_TYPE=cloud
JIRA_AUTH_TYPE=basic
TRANSPORT_MODE=http
HTTP_PORT=3000
- The server will start with Streamable HTTP endpoint:
╔════════════════════════════════════════════════════════════╗
║ 🚀 JIRA MCP Server - Streamable HTTP Transport ║
╠════════════════════════════════════════════════════════════╣
║ Protocol: MCP 2025-03-26 (Streamable HTTP) ║
║ Endpoint: http://localhost:3000/mcp ║
║ Health Check: http://localhost:3000/health ║
║ ║
║ 🔧 Supported Methods: ║
║ GET /mcp → Establish SSE connection ║
║ POST /mcp → Send JSON-RPC message ║
║ DELETE /mcp → Terminate session ║
╚════════════════════════════════════════════════════════════╝
- Configure MCP Inspector:
In MCP Inspector v0.15.x+, add a new server connection:
{
"mcpServers": {
"jira": {
"type": "sse",
"url": "http://localhost:3000/mcp"
}
}
}
- Configure Postman MCP Client:
In Postman, add a new MCP server connection:
- URL:
http://localhost:3000/mcp - Method: GET
- Transport: SSE (Server-Sent Events)
Or import the provided Postman collection: tests/manual/postman_collection.json
The server implements the MCP Streamable HTTP protocol (2025-03-26) with full session management and is compatible with MCP Inspector v0.15.x and Postman MCP Client.
4. Restart the MCP server
For STDIO mode: Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.
For HTTP mode: Simply run the server with TRANSPORT_MODE=http environment variable set.
Development
Run tests:
bun test
Watch mode for development:
bun run dev
To rebuild after changes:
bun run build
Available MCP Tools
search_issues
Search JIRA issues using JQL. Returns up to 50 results per request.
Input Schema:
{
searchString: string; // JQL search string
}
get_epic_children
Get all child issues in an epic including their comments and relationship data. Limited to 100 issues per request.
Input Schema:
{
epicKey: string; // The key of the epic issue
}
get_issue
Get detailed information about a specific JIRA issue including comments and all relationships.
Input Schema:
{
issueId: string; // The ID or key of the JIRA issue
}
create_issue
Create a new JIRA issue with specified fields.
Input Schema:
{
projectKey: string, // The project key where the issue will be created
issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
summary: string, // The issue summary/title
description?: string, // Optional issue description
fields?: { // Optional additional fields
[key: string]: any
}
}
update_issue
Update fields of an existing JIRA issue.
Input Schema:
{
issueKey: string, // The key of the issue to update
fields: { // Fields to update
[key: string]: any
}
}
add_attachment
Add a file attachment to a JIRA issue.
Input Schema:
{
issueKey: string, // The key of the issue
fileContent: string, // Base64 encoded file content
filename: string // Name of the file to be attached
}
add_comment
Add a comment to a JIRA issue. Accepts plain text and converts it to the required Atlassian Document Format internally.
Input Schema:
{
issueIdOrKey: string, // The ID or key of the issue to add the comment to
body: string // The content of the comment (plain text)
}
Data Cleaning Features
- Extracts text from Atlassian Document Format
- Tracks issue mentions in descriptions and comments
- Maintains formal issue links with relationship types
- Preserves parent/child relationships
- Tracks epic associations
- Includes comment history with author information
- Removes unnecessary metadata from responses
- Recursively processes content nodes for mentions
- Deduplicates issue mentions
Technical Details
- Built with TypeScript in strict mode
- Uses Bun runtime for improved performance
- Vite for optimized builds
- Dual transport support:
- STDIO: For Claude Desktop and Cline (default)
- Streamable HTTP (MCP 2025-03-26): For MCP Inspector v0.15.x+ and Postman MCP Client
- Session management with automatic cleanup (1-hour expiry)
- UUID-based session tracking with
Mcp-Session-Idheaders - Uses JIRA REST API v3 (Cloud) or v2 (Server/Data Center)
- Supports multiple authentication methods:
- Basic authentication with API tokens or username/password
- Bearer authentication with Personal Access Tokens (PATs)
- Batched API requests for related data
- Optimized response payloads for AI context windows
- Efficient transformation of complex Atlassian structures
- Robust error handling
- Rate limiting considerations
- Maximum limits:
- Search results: 50 issues per request
- Epic children: 100 issues per request
- Support for multipart form data for secure file attachments
- Automatic content type detection and validation
- CORS enabled for cross-origin requests in HTTP mode
Error Handling
The server implements a comprehensive error handling strategy:
- Network error detection and appropriate messaging
- HTTP status code handling (especially 404 for issues)
- Detailed error messages with status codes
- Error details logging to console
- Input validation for all parameters
- Safe error propagation through MCP protocol
- Specialized handling for common JIRA API errors
- Base64 validation for attachments
- Multipart request failure handling
- Rate limit detection
- Attachment parameter validation
Transport Modes Comparison
| Feature | STDIO Transport | Streamable HTTP Transport |
|---|---|---|
| Use Case | Claude Desktop, Cline | MCP Inspector, Postman, HTTP clients |
| Protocol | MCP over stdio | MCP Streamable HTTP (2025-03-26) |
| Configuration | MCP config file | Environment variables |
| Connection | Process stdin/stdout | HTTP + Server-Sent Events |
| Default Port | N/A | 3000 |
| Session Management | N/A | Yes (UUID-based, 1-hour expiry) |
| Endpoints | N/A | GET/POST/DELETE /mcp |
| CORS Support | N/A | Yes |
| Health Check | No | Yes (/health endpoint) |
| Best For | Production AI assistants | Development, testing, debugging |
| Inspector Compatibility | N/A | v0.15.x+ |
Manual Testing
The tests/manual/ directory contains comprehensive test scripts:
test_sse.sh- Test SSE connection and session establishmenttest_initialize.sh- Test initialize handshaketest_tools_list.sh- Test tools/list requesttest_tool_execution.sh- Test tool execution (search_issues)postman_collection.json- Complete Postman test collectionREADME.md- Detailed testing instructions
Run all tests:
cd tests/manual
./test_sse.sh
./test_initialize.sh
./test_tools_list.sh
./test_tool_execution.sh
LICENCE
This project is licensed under the MIT License - see the LICENCE file for details.