Jira Insights MCP
The Jira Insights MCP server enables you to interact with Jira Service Management asset data through these capabilities:
Manage object schemas: Create, read, update, and delete schemas with options to include object types, attributes, or statistics with pagination support.
Manage object types: Perform CRUD operations on object types within specific schemas, with customizable response details.
Manage objects: Execute CRUD operations on individual objects with extensive response customization options.
Query using AQL: Construct complex queries with the Atlassian Query Language, supporting filtering, pagination, and schema validation.
Access resources: Retrieve instance summaries, AQL syntax documentation, schema listings, and detailed object type information.
Customize responses: Tailor data with options for simplified structures, attribute depth control, and extended Jira issue information.
Enables interaction with Atlassian's Jira Insights service for asset management, supporting schema operations, object type management, and object manipulation through the Atlassian API.
Provides tools for managing Jira Insights (JSM) asset schemas, including CRUD operations for object schemas, object types, and objects, as well as querying objects using Atlassian Query Language (AQL).
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 Insights MCP list all schemas in my Jira instance"
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 Insights MCP
A Model Context Protocol (MCP) server for managing Jira Insights (JSM) asset schemas.
Last updated: 2025-04-09
Overview
This MCP server provides tools for interacting with Jira Insights (JSM) asset schemas through the Model Context Protocol. It allows you to manage object schemas, object types, and objects in Jira Insights.
Related MCP server: MCP Atlassian
Features
Manage object schemas (create, read, update, delete)
Manage object types (create, read, update, delete)
Manage objects (create, read, update, delete)
Query objects using AQL (Atlassian Query Language)
Prerequisites
Node.js 20 or later
Docker (for containerized deployment)
Jira Insights instance with API access
Jira API token with appropriate permissions
Installation
Local Development
Clone the repository:
git clone https://github.com/aaronsb/jira-insights-mcp.git cd jira-insights-mcpInstall dependencies:
npm installBuild the project:
npm run build
Docker
Build the Docker image:
./scripts/build-local.shUsage
MCP Configuration
To use this MCP server with Claude or other AI assistants that support the Model Context Protocol, add it to your MCP configuration using one of the following methods:
Local Build Configuration
If you've built the project locally, use this configuration:
{
"mcpServers": {
"jira-insights": {
"command": "node",
"args": ["/path/to/jira-insights-mcp/build/index.js"],
"env": {
"JIRA_API_TOKEN": "your-api-token",
"JIRA_EMAIL": "your-email@example.com",
"JIRA_HOST": "https://your-domain.atlassian.net",
"LOG_MODE": "strict"
}
}
}
}Docker-based Configuration
If you prefer to use the Docker image (recommended for most users), use this configuration:
{
"mcpServers": {
"jira-insights": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "JIRA_API_TOKEN",
"-e", "JIRA_EMAIL",
"-e", "JIRA_HOST",
"ghcr.io/aaronsb/jira-insights-mcp:latest"
],
"env": {
"JIRA_API_TOKEN": "your-api-token",
"JIRA_EMAIL": "your-email@example.com",
"JIRA_HOST": "https://your-domain.atlassian.net"
}
}
}
}This Docker-based configuration pulls the latest image from GitHub Container Registry and runs it with the necessary environment variables.
Running Locally for Development
For local development and testing:
# Build the Docker image
./scripts/build-local.sh
# Run the Docker container
JIRA_API_TOKEN=your_token JIRA_EMAIL=your_email JIRA_HOST=your_host ./scripts/run-local.shAvailable Tools
manage_jira_insight_schema
Manage Jira Insights object schemas with CRUD operations.
{
"operation": "list",
"maxResults": 10
}manage_jira_insight_object_type
Manage Jira Insights object types with CRUD operations.
{
"operation": "list",
"schemaId": "1",
"maxResults": 20
}manage_jira_insight_object
Manage Jira Insights objects with CRUD operations and AQL queries.
{
"operation": "query",
"aql": "objectType = \"Application\"",
"maxResults": 10
}Available Resources
The MCP server provides several resources for accessing Jira Insights data:
jira-insights://instance/summary- High-level statistics about the Jira Insights instancejira-insights://aql-syntax- Comprehensive guide to Assets Query Language (AQL) syntax with examplesjira-insights://schemas/all- Complete list of all schemas with their object typesjira-insights://schemas/{schemaId}/full- Complete definition of a specific schema including object typesjira-insights://schemas/{schemaId}/overview- Overview of a specific schema including metadata and statisticsjira-insights://object-types/{objectTypeId}/overview- Overview of a specific object type including attributes and statistics
Planned Improvements
We are working on several improvements to enhance the functionality and usability of the Jira Insights MCP:
High Priority Improvements
Enhanced Error Handling
More detailed error messages with specific validation issues
Suggested fixes for common errors
Operation-specific examples to help users correct issues
AQL Query Improvements
Validation and formatting utilities for AQL queries
Schema-specific example queries
Better error messages for query issues
Attribute Discovery Enhancement
Improved attribute retrieval for object types
Caching for better performance
Better handling of the "expand" parameter
Medium Priority Improvements
Object Template Generation
Templates for creating objects based on object types
Type-specific placeholder generation
Validation rules in templates
Example Query Library
Schema-specific example queries
Context-aware query suggestions
Query templates for common operations
Improved Documentation
Enhanced AQL syntax documentation
Operation-specific documentation
Common error scenarios and solutions
For more details on the planned improvements, see:
TODO.md- Comprehensive todo list with all tasks organized by priorityIMPLEMENTATION_PLAN.md- Detailed implementation plans for the high-priority improvementsHANDLER_IMPROVEMENTS.md- Specific changes needed for each handler fileIMPROVEMENT_SUMMARY.md- Concise summary of the planned improvementsdocs/API_MIGRATION_TODO.md- Status of the API migration and planned improvements
Development
Scripts
npm run build: Build the TypeScript codenpm run lint: Run ESLintnpm run lint:fix: Run ESLint with auto-fixnpm run test: Run testsnpm run watch: Watch for changes and rebuildnpm run generate-diagrams: Generate TypeScript dependency diagrams
Docker Scripts
./scripts/build-local.sh: Build the Docker image./scripts/run-local.sh: Run the Docker container
Troubleshooting
Common Issues
AQL Query Validation Errors
Ensure values with spaces are enclosed in quotes:
Name = "John Doe"Use uppercase for logical operators:
AND,OR(notand,or)Check that object types and attributes exist in your schema
Object Type Attribute Issues
When using the "expand" parameter with "attributes", ensure the object type exists
Check that you have permissions to view the attributes
API Connection Issues
Verify your Jira API token has the necessary permissions
Check that the Jira host URL is correct
Ensure your network allows connections to the Jira API
License
MIT
Available Tools
3 toolsmanage_jira_insight_objectC
Manage Jira Insights objects with CRUD operations and AQL queries
Inputs: operation (required), aql, attributes, expand, +12 more.
manage_jira_insight_object_typeC
Manage Jira Insights object types with CRUD operations
Inputs: operation (required), description, expand, icon, +5 more.
manage_jira_insight_schemaC
Manage Jira Insights object schemas with CRUD operations
Inputs: operation (required), description, expand, maxResults, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose targeting different Jira Insights components: objects, object types, and schemas. The descriptions specify unique domains (objects, object types, schemas) with no overlap in functionality, making it easy for an agent to select the correct tool.
All tool names follow a consistent verb_noun pattern with 'manage_jira_insight_' prefix followed by the specific component (object, object_type, schema). This predictable naming convention enhances readability and usability across the tool set.
With only 3 tools, the count feels thin for a server named 'Jira Insights MCP', which might imply broader functionality. However, it covers core management areas adequately, though it could benefit from additional tools for querying or reporting to be more comprehensive.
The tools provide CRUD operations for key Jira Insights components (objects, types, schemas), covering essential management tasks. A minor gap exists in lacking dedicated query or analysis tools beyond AQL mentioned in one description, but core workflows are well-supported.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for Product Management
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceModel Context Protocol (MCP) server for Atlassian Cloud products (Confluence and Jira). This integration is designed specifically for Atlassian Cloud instances and does not support Atlassian Server or Data Center deployments.6,136MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to interact with Atlassian products (Confluence and Jira) for content management, issue tracking, and project management through a standardized interface.4,948 npm6MIT
- -licenseNot gradedqualityCmaintenanceA local MCP server for administering Atlassian Cloud Assets and Jira, providing hundreds of tools for schemas, projects, workflows, and more.-
- AlicenseNot gradedqualityDmaintenanceModel Context Protocol (MCP) server for Atlassian products (Confluence and Jira). Supports both Cloud and Server/Data Center deployments.MIT