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
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
Prerequisites
- Bun (v1.0.0 or higher)
- JIRA account with API access
Environment Variables
Installation & Setup
1. Clone the repository:
2. Install dependencies and build:
3. Configure the MCP server:
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:4. Restart the MCP server.
Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.
Development
Run tests:
Watch mode for development:
To rebuild after changes:
Available MCP Tools
search_issues
Search JIRA issues using JQL. Returns up to 50 results per request.
Input Schema:
get_epic_children
Get all child issues in an epic including their comments and relationship data. Limited to 100 issues per request.
Input Schema:
get_issue
Get detailed information about a specific JIRA issue including comments and all relationships.
Input Schema:
create_issue
Create a new JIRA issue with specified fields.
Input Schema:
update_issue
Update fields of an existing JIRA issue.
Input Schema:
add_attachment
Add a file attachment to a JIRA issue.
Input Schema:
add_comment
Add a comment to a JIRA issue. Accepts plain text and converts it to the required Atlassian Document Format internally.
Input Schema:
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
- Uses JIRA REST API v3
- Basic authentication with API tokens
- 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:
- Support for multipart form data for secure file attachments
- Automatic content type detection and validation
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
LICENCE
This project is licensed under the MIT License - see the LICENCE file for details.
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
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
Prerequisites
- Bun (v1.0.0 or higher)
- JIRA account with API access
Environment Variables
Installation & Setup
1. Clone the repository:
2. Install dependencies and build:
3. Configure the MCP server:
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:4. Restart the MCP server.
Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.
Development
Run tests:
Watch mode for development:
To rebuild after changes:
Available MCP Tools
search_issues
Search JIRA issues using JQL. Returns up to 50 results per request.
Input Schema:
get_epic_children
Get all child issues in an epic including their comments and relationship data. Limited to 100 issues per request.
Input Schema:
get_issue
Get detailed information about a specific JIRA issue including comments and all relationships.
Input Schema:
create_issue
Create a new JIRA issue with specified fields.
Input Schema:
update_issue
Update fields of an existing JIRA issue.
Input Schema:
add_attachment
Add a file attachment to a JIRA issue.
Input Schema:
add_comment
Add a comment to a JIRA issue. Accepts plain text and converts it to the required Atlassian Document Format internally.
Input Schema:
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
- Uses JIRA REST API v3
- Basic authentication with API tokens
- 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:
- Support for multipart form data for secure file attachments
- Automatic content type detection and validation
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
LICENCE
This project is licensed under the MIT License - see the LICENCE file for details.