JIRA MCP Server
Provides read-only access to JIRA REST API, enabling querying and retrieval of issues, projects, users, and field metadata from JIRA Server/Data Center instances.
Click on "Deploy 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., "@JIRA MCP Server search for high priority issues in project ABC"
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.
JIRA MCP Server
A Model Context Protocol (MCP) server that provides read-only access to JIRA REST API, enabling LLMs to query and retrieve information from JIRA instances.
Features
Issue Operations
Search Issues - Execute JQL queries to find issues
Get Issue Details - Retrieve comprehensive information about specific issues
Get Issue Comments - Fetch comments for issues
Get Issue Transitions - View available workflow transitions
Project Operations
List Projects - Get all accessible projects
Get Project Details - Retrieve detailed project information
Search Projects - Find projects by various criteria
User Operations
Get Current User - Retrieve authenticated user information
Get User - Get details about specific users
Search Users - Find users by query
Field Discovery Operations
Get Issue Types - Get all issue types for a project
Get Issue Type Fields - Get all fields available for a specific issue type
Get Issue Field Names - Get all field IDs and names for a specific issue
Search Issue Fields - Search for fields by name in a specific issue with partial matching
Related MCP server: Jira MCP Integration
Architecture
This MCP server follows a modular architecture designed for maintainability and extensibility:
Project Structure
JIRA-API-MCP/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── server.ts # Server initialization and tool registration
│ ├── client/
│ │ ├── JiraClient.ts # JIRA API client wrapper with axios
│ │ └── types.ts # TypeScript interfaces for JIRA data models
│ ├── tools/
│ │ ├── issues.ts # Issue-related MCP tool implementations
│ │ ├── projects.ts # Project-related MCP tool implementations
│ │ ├── users.ts # User-related MCP tool implementations
│ │ └── fields.ts # Field discovery MCP tool implementations
│ └── __tests__/
│ ├── tools-direct.test.ts # Integration tests for tool handlers
│ ├── jira.test.ts # Direct JIRA API tests
│ └── generate-mcp-docs.ts # Documentation generation utility
├── dist/ # Compiled JavaScript output
├── __tool_response_logs__/ # Test response captures
└── docs/
├── CLAUDE.md # Instructions for AI assistants
├── INSPECTOR_GUIDE.md # MCP Inspector usage guide
├── MCP_TOOL_DOCUMENTATION.md # Detailed tool specifications
└── TEST_SUMMARY.md # Testing documentationKey Components
MCP Server Layer (
server.ts)Implements Model Context Protocol specification
Registers all available tools with the MCP SDK
Handles tool dispatch and response formatting
JIRA Client (
client/JiraClient.ts)Axios-based HTTP client for JIRA REST API v2
Handles authentication via Bearer tokens
Implements retry logic and error handling
Manages request/response transformations
Tool Modules (
tools/*.ts)Each module exports tool definitions with:
Zod schemas for input validation
Handler functions that call the JIRA client
Consistent error handling and response formatting
Tools return standardized
{success, data/error}structure
Type System (
client/types.ts)Comprehensive TypeScript interfaces for JIRA entities
Ensures type safety across the application
Documents expected data structures
Data Flow
Request Flow:
MCP Client → MCP Server → Tool Handler → JIRA Client → JIRA APIResponse Flow:
JIRA API → JIRA Client → Tool Handler → MCP Server → MCP Client
Design Principles
Modularity: Each tool is self-contained with its own validation and logic
Type Safety: Full TypeScript coverage with strict typing
Error Resilience: Graceful error handling at each layer
Testability: Comprehensive test suite with response capture
Documentation: Auto-generated docs from actual API responses
Installation
From NPM
npm install @mcp/jira-serverFrom Source
git clone https://github.com/jl-0/JIRA-API-MCP.git
cd JIRA-API-MCP
npm install
npm run buildConfiguration
The server requires JIRA authentication credentials. You can provide these via environment variables or a .env file:
# Required
# For Server/Data Center: https://your-server.com/jira
# For Cloud: https://your-domain.atlassian.net (not currently supported)
JIRA_BASE_URL=https://your-server.com/jira
# For Server/Data Center: Personal Access Token (PAT)
JIRA_API_TOKEN=your-personal-access-token
# Optional
JIRA_MAX_RESULTS=50 # Default max results per request
JIRA_TIMEOUT=30000 # Request timeout in millisecondsJIRA Server/Data Center Support
This MCP server is designed for JIRA Server and Data Center installations using:
REST API v2 endpoints
Personal Access Token (PAT) authentication with Bearer tokens
Compatible with JIRA Server 8.14+ and JIRA Service Management 4.15+
Getting a Personal Access Token (PAT)
For JIRA Server/Data Center:
Log in to your JIRA instance
Navigate to your Profile → Personal Access Tokens
Click "Create token"
Give it a descriptive name and set expiration
Copy the token immediately (it won't be shown again)
Use this token as
JIRA_API_TOKENin your configuration
The server uses Bearer token authentication: Authorization: Bearer <token>
Note: JIRA Cloud uses a different authentication mechanism (API tokens with Basic auth) which is not currently supported by this server.
Usage
With Claude Desktop
Add the server to your Claude Desktop configuration:
{
"mcpServers": {
"jira": {
"command": "npx",
"args": ["@jl-0/jira-server"],
"env": {
"JIRA_BASE_URL": "https://your-domain.atlassian.net",
"JIRA_API_TOKEN": "your-api-token"
}
}
}
}As a Standalone Server
# Using environment variables
export JIRA_BASE_URL=https://your-domain.atlassian.net
export JIRA_API_TOKEN=your-api-token
npm start
# Or using a .env file
npm startTesting & Development
Interactive Testing with MCP Inspector
The MCP Inspector provides an interactive web interface for testing all server capabilities:
# Launch inspector with TypeScript source (development)
npm run inspect
# Build and inspect with compiled JavaScript
npm run inspect:builtThe inspector will open at http://localhost:6274 and allow you to:
Test all available tools with custom parameters
View real-time server responses
Debug authentication and connectivity issues
Monitor server logs and notifications
See INSPECTOR_GUIDE.md for detailed usage instructions.
Automated Testing
Run the comprehensive test suite:
# Run all tests
npm test
# Run direct tool integration tests
npm run test:direct
# Generate documentation from test responses
npm run test:generate-docsTest outputs are saved to __tool_response_logs__/ for analysis.
See TEST_SUMMARY.md for test documentation.
Available Tools
jira_search_issues
Search for issues using JQL (JIRA Query Language).
Parameters:
jql(required): JQL query stringmaxResults: Maximum results to return (default: 50)fields: Array of fields to includeexpand: Array of data to expandstartAt: Starting index for pagination
Example:
{
"jql": "project = PROJ AND status = 'In Progress'",
"maxResults": 10
}jira_get_issue
Get detailed information about a specific issue.
Parameters:
issueIdOrKey(required): Issue ID or key (e.g., PROJ-123)fields: Array of fields to includeexpand: Array of data to expand
jira_get_issue_comments
Get comments for a specific issue.
Parameters:
issueIdOrKey(required): Issue ID or keymaxResults: Maximum results (default: 50)startAt: Starting index for pagination
jira_get_issue_transitions
Get available transitions for an issue.
Parameters:
issueIdOrKey(required): Issue ID or keyincludeUnavailable: Include unavailable transitions (default: false)
jira_list_projects
List all accessible projects.
Parameters:
expand: Array of additional data to expandrecent: Return only most recent projects
jira_get_project
Get detailed project information.
Parameters:
projectIdOrKey(required): Project ID or keyexpand: Array of additional data to expand
jira_search_projects
Search for projects.
Parameters:
query: Search query stringmaxResults: Maximum results (default: 50)startAt: Starting indexorderBy: Sort order fieldtypeKey: Project type keycategoryId: Project category IDaction: Filter by permission (view/browse/edit)
jira_get_current_user
Get information about the authenticated user.
Parameters:
expand: Additional data to expand
jira_search_users
Search for users.
Parameters:
query: Search query matching display name and emailaccountId: Find user by account IDmaxResults: Maximum results (default: 50)startAt: Starting index
jira_get_issue_types
Get all issue types available for a specific project.
Parameters:
projectIdOrKey(required): Project ID or keymaxResults: Maximum results (default: 50)startAt: Starting index
jira_get_issue_type_fields
Get all fields available for a specific issue type in a project.
Parameters:
projectIdOrKey(required): Project ID or keyissueTypeId(required): Issue type IDmaxResults: Maximum results (default: 50)startAt: Starting index
jira_get_issue_field_names
Get all field IDs and names for a specific JIRA issue.
Parameters:
issueIdOrKey(required): Issue ID or key
Example:
{
"issueIdOrKey": "IDS-10314"
}jira_search_issue_fields
Search for specific fields by name in a JIRA issue.
Parameters:
issueIdOrKey(required): Issue ID or keysearchTerms(required): Array of search terms to match against field names
Example:
{
"issueIdOrKey": "IDS-10314",
"searchTerms": ["test", "procedure", "story points"]
}JQL Examples
Common JQL queries you can use with jira_search_issues:
-- Find all open issues assigned to me
assignee = currentUser() AND resolution = Unresolved
-- Find high priority bugs
priority = High AND issuetype = Bug
-- Issues updated in the last week
updated >= -1w
-- Issues in specific projects
project in (PROJ1, PROJ2) AND status = "To Do"
-- Issues with specific labels
labels in ("backend", "api")
-- Issues created this month
created >= startOfMonth()
-- Find issues by reporter
reporter = "john.doe@example.com"
-- Complex query
project = PROJ AND (
(priority = High AND status = "In Progress") OR
(priority = Critical AND status != Done)
) ORDER BY created DESCDevelopment
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run in development mode
npm run dev
# Run tests
npm test
# Lint code
npm run lint
# Format code
npm run formatPublishing to npm
First-time Setup
Ensure you have an npm account at npmjs.com
Login to npm from your terminal:
npm login
Publishing Process
Update the version in
package.jsonfollowing semantic versioning:npm version patch # for bug fixes (0.1.0 -> 0.1.1) npm version minor # for new features (0.1.0 -> 0.2.0) npm version major # for breaking changes (0.1.0 -> 1.0.0)Build the project:
npm run clean npm run buildTest locally (optional but recommended):
npm link # In another project: npm link @mcp/jira-serverPublish to npm:
npm publish --access publicCreate a git tag and push:
git push origin main git push origin --tags
Package Information
Package Name: @mcp/jira-server
Author: Jeff Leach
Repository: https://github.com/jl-0/JIRA-API-MCP
License: MIT
Error Handling
The server provides detailed error messages for common issues:
Authentication failures - Check your API token and email
Permission errors - Ensure your account has access to the requested resources
Rate limiting - The server implements retry logic for rate limits
Network issues - Check your internet connection and JIRA instance URL
Security
API tokens are never logged or exposed
All communication with JIRA uses HTTPS
Uses Bearer token authentication for secure API access
Credentials should be stored securely using environment variables
The server provides read-only access by default
Limitations
This is a read-only implementation (no issue creation/updates)
Rate limits are determined by your JIRA instance
Some JIRA Cloud features may not be available on JIRA Server/Data Center
Field discovery tools use the editmeta endpoint which returns fields available for editing
Future Enhancements
Planned features for future releases:
Issue creation and updates
Attachment handling
Webhook support
Advanced filtering and field customization
Bulk operations
Sprint and board operations (JIRA Software)
Service desk operations (JIRA Service Management)
Documentation
This project maintains comprehensive documentation:
CLAUDE.md - Instructions for AI assistants working with this codebase
INSPECTOR_GUIDE.md - Detailed guide for using MCP Inspector
MCP_TOOL_DOCUMENTATION.md - Complete tool specifications and examples
TEST_SUMMARY.md - Testing approach and coverage
SCRIPTS_REFERENCE.md - NPM scripts quick reference
Documentation Maintenance
When making changes to the codebase:
Update README.md when adding features or changing configuration
Run tests to capture new response formats:
npm run test:directGenerate documentation from test outputs:
npm run test:generate-docsUpdate tool documentation if parameters or responses change
Follow guidelines in CLAUDE.md for consistent documentation
Contributing
Contributions are welcome! Please:
Read CLAUDE.md for development guidelines
Update documentation when making changes
Add tests for new functionality
Ensure all tests pass:
npm testRun linting:
npm run lintSubmit a Pull Request with clear description
License
MIT
Support
For issues and questions, please use the GitHub Issues page.
Available Tools
14 toolsjira_get_current_userA
Get information about the currently authenticated JIRA user
Inputs: expand.
jira_get_issueA
Get detailed information about a specific JIRA issue by its key (e.g., "IDS-10194"). Returns comprehensive issue details including summary, description, status, assignee, and custom fields. CRITICAL: Always use the fields parameter to request only specific fields needed - requesting all fields or omitting this parameter returns excessive data and may fail. For custom fields, use field discovery workflow first: (1) Get issue type with fields: ["issuetype", "project"], (2) Use jira_get_issue_type_fields to find field names/IDs, (3) Request only needed fields by name or customfield_XXXX ID. Example: fields: ["summary", "customfield_10001", "status"].
Inputs: issueIdOrKey (required), expand, fields, properties, +1 more.
jira_get_issue_commentsA
Get all comments for a specific JIRA issue by its key (e.g., "IDS-10194"). Returns a paginated list of comments with author and timestamp information.
Inputs: issueIdOrKey (required), startAt, maxResults.
jira_get_issue_field_namesA
Get all field IDs and their corresponding names for a specific JIRA issue. This tool retrieves the editmeta for an issue and returns a simplified list of field IDs (like "customfield_25931") mapped to their human-readable names (like "Target start"). Use this when you need to discover what fields are available for a specific issue.
Inputs: issueIdOrKey (required).
jira_get_issue_transitionsA
Get available workflow transitions for a JIRA issue by its key (e.g., "IDS-10194"). Shows what status changes are possible for the issue (e.g., Open -> In Progress, In Progress -> Resolved).
Inputs: issueIdOrKey (required), includeUnavailable.
jira_get_issue_type_fieldsA
Get all fields available for a specific issue type in a project. Returns detailed field metadata including which fields are required, their types, allowed values, and default values. Use this to understand what fields can be queried or set for a specific issue type.
Inputs: issueTypeId (required), projectIdOrKey (required), startAt, maxResults.
jira_get_issue_typesA
Get all issue types available for a specific project. Returns issue type metadata including IDs and names. Use this to discover what issue types exist in a project before querying for their specific fields.
Inputs: projectIdOrKey (required), startAt, maxResults.
jira_get_projectB
Get detailed information about a specific JIRA project
Inputs: projectIdOrKey (required), expand.
jira_get_userB
Get information about a specific JIRA user by account ID
Inputs: accountId (required), expand.
jira_list_projectsA
List all JIRA projects accessible to the authenticated user
Inputs: expand, recent.
jira_search_issue_fieldsA
Search for specific fields by name in a JIRA issue. Provide an issue key and one or more search terms, and this tool will return matching field IDs and names. Supports partial/fuzzy matching - for example, searching for "test" will match "Task Test Procedure". Use this when you need to find the field ID for a specific field name.
Inputs: searchTerms (required), issueIdOrKey (required).
jira_search_issuesA
Search for JIRA issues using JQL (JIRA Query Language). Use this to find issues based on various criteria like project, status, assignee, text content, etc. Returns a summary of matching issues.
Inputs: jql (required), expand, fields, startAt, +2 more.
jira_search_projectsC
Search for JIRA projects based on various criteria
Inputs: query, action, orderBy, startAt, +3 more.
jira_search_usersB
Search for JIRA users by query string
Inputs: query, startAt, accountId, maxResults.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a clear resource and action, but the three field-discovery tools (jira_get_issue_type_fields, jira_get_issue_field_names, jira_search_issue_fields) have overlapping purposes for discovering field IDs, which could cause confusion. However, their descriptions differentiate them sufficiently by scope (issue type vs issue vs search).
All tools follow a consistent jira_<verb>_<noun> pattern with verbs limited to get, list, and search. Naming is uniform, predictable, and easy to navigate.
At 14 tools, the count is appropriate for a JIRA server covering projects, issues, comments, transitions, users, and field metadata. Each tool has a clear role, though the set is somewhat read-heavy.
The server lacks any create, update, or transition operations, so agents cannot modify issues, add comments, or change statuses. It provides broad read capabilities but is severely incomplete for a JIRA MCP server that would normally support issue lifecycle management.
Related MCP Connectors
Read-only Google Search Console and Google Analytics for AI agents.
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Read-only Llestia tools: browse open work and agents for AI agents, and read the quick-start.
Read-only search of 2,189 AI agent tools (MCP servers, x402 APIs) with daily automated trust scores.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides integration with Jira's REST API, allowing AI assistants to manage Jira issues programmatically.11MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Jira Cloud through the REST API, supporting project management, issue operations (create, read, update, delete), JQL search, task assignments, and status transitions.-
- AlicenseNot gradedqualityDmaintenanceEnables AI models to search Jira issues using JQL and retrieve issue details through the Jira 9.12.14 API.20 npmMIT
- AlicenseAqualityDmaintenanceEnables LLMs to interact with Jira Cloud through the official REST API v3, supporting operations like creating issues, searching with JQL, fetching issue details, and managing transitions.9ISC