JasperReports MCP Server

A comprehensive Node.js Model Context Protocol (MCP) server for JasperReports Server REST API v2. This server enables AI assistants and developers to perform all major JasperReports operations including authentication, resource management, report execution, job scheduling, and administrative tasks through standardized MCP tools.

Perfect for integrating JasperReports functionality into AI-powered IDEs like Cursor, Kiro, Windsurf, Claude Desktop, and any other MCP-compatible development environment.

Features

🔌 MCP Compatible: Works seamlessly with Cursor, Kiro, Windsurf, and other MCP-enabled IDEs
🔐 Complete JasperReports Integration: Full support for JasperReports Server REST API v2
🔑 Multiple Authentication Methods: Basic, login service, and argument-based authentication
📁 Resource Management: Upload, list, update, and delete reports and resources
📊 Report Execution: Synchronous and asynchronous report generation in multiple formats (PDF, Excel, CSV, etc.)
⏰ Job Scheduling: Create and manage scheduled report jobs with cron expressions
🎛️ Input Controls: Handle report parameters and cascading controls
👥 Administrative Tools: User, role, and permission management
🧪 Test Server: HTTP endpoint for testing and validation
🛡️ Enterprise Ready: SSL support, timeout handling, and comprehensive error management
📝 Comprehensive Logging: Debug and production logging with configurable levels

IDE Integration

Cursor IDE

Install the MCP server globally:

npm install -g jasperreports-mcp-server

Add to your Cursor settings (.cursor-settings/mcp.json):

{
  "mcpServers": {
    "jasperreports-server": {
      "command": "npx",
      "args": ["jasperreports-mcp-server"],
      "env": {
        "JASPER_URL": "http://localhost:8080/jasperserver",
        "JASPER_USERNAME": "jasperadmin",
        "JASPER_PASSWORD": "jasperadmin",
        "JASPER_AUTH_TYPE": "basic"
      }
    }
  }
}

Kiro IDE

Install the server:

npm install -g jasperreports-mcp-server

Configure in .kiro/settings/mcp.json:

{
  "mcpServers": {
    "jasperreports-server": {
      "command": "jasperreports-mcp-server",
      "env": {
        "JASPER_URL": "http://localhost:8080/jasperserver",
        "JASPER_USERNAME": "jasperadmin",
        "JASPER_PASSWORD": "jasperadmin"
      },
      "autoApprove": [
        "jasper_authenticate",
        "jasper_test_connection",
        "jasper_list_resources"
      ]
    }
  }
}

Windsurf IDE

Install globally:

npm install -g jasperreports-mcp-server

Add to Windsurf MCP configuration:

{
  "mcpServers": {
    "jasperreports-server": {
      "command": "npx",
      "args": ["jasperreports-mcp-server"],
      "env": {
        "JASPER_URL": "https://your-jasper-server.com/jasperserver",
        "JASPER_USERNAME": "your-username",
        "JASPER_PASSWORD": "your-password",
        "JASPER_SSL_VERIFY": "true"
      }
    }
  }
}

Claude Desktop

Install the server:

npm install -g jasperreports-mcp-server

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "jasperreports-server": {
      "command": "jasperreports-mcp-server",
      "env": {
        "JASPER_URL": "http://localhost:8080/jasperserver",
        "JASPER_USERNAME": "jasperadmin",
        "JASPER_PASSWORD": "jasperadmin"
      }
    }
  }
}

Other MCP-Compatible IDEs

For any IDE that supports the Model Context Protocol:

Install the server:

npm install -g jasperreports-mcp-server

Add the server configuration to your IDE's MCP settings file:

{
  "mcpServers": {
    "jasperreports-server": {
      "command": "jasperreports-mcp-server",
      "env": {
        "JASPER_URL": "your-jasper-server-url",
        "JASPER_USERNAME": "your-username",
        "JASPER_PASSWORD": "your-password"
      }
    }
  }
}

Quick Start

Local Development

Clone and install:

git clone https://github.com/mr-wolf-gb/jasperreports-mcp-server.git
cd jasperreports-mcp-server
npm install

Configure environment variables:

cp .env.example .env
# Edit .env with your JasperReports Server details

Start the server:

# Start the MCP server
npm start

# Start in development mode with auto-reload
npm run dev

# Start the test server for HTTP testing
npm run test-server

Production Installation

# Install globally
npm install -g jasperreports-mcp-server

# Or use with npx (recommended)
npx jasperreports-mcp-server

Development

Project Structure

src/
├── config/          # Configuration management
├── services/        # Business logic services
├── utils/           # Utility functions
├── models/          # Data models and schemas
├── tools/           # MCP tool definitions
├── index.js         # Main MCP server entry point
└── testServer.js    # Express test server

test/
├── unit/            # Unit tests
├── integration/     # Integration tests
├── fixtures/        # Test data and fixtures
└── utils/           # Test utilities

docs/                # Documentation and examples

Available Scripts

npm start - Start the MCP server
npm run dev - Start with auto-reload
npm test - Run all tests
npm run test:watch - Run tests in watch mode
npm run test:coverage - Run tests with coverage report
npm run lint - Run ESLint
npm run lint:fix - Fix ESLint issues
npm run format - Format code with Prettier
npm run format:check - Check code formatting
npm run test-server - Start HTTP test server

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Configuration

Environment Variables

The server is configured through environment variables:

Variable	Description	Default	Required
`JASPER_URL`	JasperReports Server URL	-	✅
`JASPER_USERNAME`	Username for authentication	-	✅
`JASPER_PASSWORD`	Password for authentication	-	✅
`JASPER_AUTH_TYPE`	Authentication method (basic/login/argument)	basic	❌
`JASPER_ORGANIZATION`	Organization for multi-tenant setups	-	❌
`JASPER_TIMEOUT`	Request timeout in milliseconds	30000	❌
`JASPER_DEBUG_MODE`	Enable debug logging	false	❌
`JASPER_SSL_VERIFY`	Verify SSL certificates	true	❌
`TEST_SERVER_PORT`	Port for HTTP test server	3000	❌
`TEST_SERVER_ENABLED`	Enable HTTP test server	false	❌
`NODE_ENV`	Node.js environment	production	❌
`LOG_LEVEL`	Logging level (error/warn/info/debug)	info	❌

Configuration Examples

The config/ directory contains ready-to-use MCP configuration examples:

mcp-development.json: Local development with debug logging
mcp-production.json: Production setup with security best practices
mcp-docker.json: Docker-based deployment configuration

Copy the appropriate configuration to your IDE's MCP settings and customize the environment variables.

Available MCP Tools

The server provides 40+ MCP tools organized into logical categories:

🔐 Authentication & Connection

jasper_authenticate - Authenticate with JasperReports Server
jasper_test_connection - Test server connectivity and health

📁 Resource Management

jasper_upload_resource - Upload JRXML reports and resources
jasper_list_resources - List repository resources with filtering
jasper_get_resource - Retrieve resource details and content
jasper_update_resource - Update existing resources
jasper_delete_resource - Delete resources and folders

📊 Report Execution

jasper_run_report_sync - Execute reports synchronously (PDF, Excel, CSV, etc.)
jasper_run_report_async - Start asynchronous execution for large reports
jasper_get_execution_status - Check execution status and progress
jasper_get_execution_result - Retrieve execution results and files
jasper_cancel_execution - Cancel running executions

⏰ Job Scheduling

jasper_create_job - Create scheduled jobs with cron expressions
jasper_list_jobs - List existing jobs with filtering
jasper_update_job - Modify job schedules and parameters
jasper_delete_job - Remove scheduled jobs
jasper_run_job_now - Execute jobs immediately

🎛️ Input Controls & Parameters

jasper_get_input_controls - Get report parameters and controls
jasper_set_input_control_values - Set parameter values for cascading controls
jasper_validate_input_controls - Validate parameter values

👥 User & Role Management

jasper_create_user - Create new user accounts
jasper_list_users - List users with filtering
jasper_update_user - Update user details and roles
jasper_create_role - Create new roles
jasper_list_roles - List available roles

🔒 Permissions & Security

jasper_get_permissions - Get resource permissions
jasper_set_permissions - Set resource permissions for users/roles

🏢 Domain Management

jasper_list_domains - List semantic layer domains
jasper_get_domain - Get domain definitions
jasper_get_domain_schema - Get domain schema and fields

🛠️ Utilities & Templates

jasper_get_report_template - Get JRXML report templates
jasper_get_datasource_structure - Get datasource configuration templates

📊 Health & Monitoring

jasper_health_status - Get comprehensive health status
jasper_deep_health_check - Perform deep system health checks
jasper_performance_metrics - Get performance and memory metrics
jasper_component_health - Test specific system components
jasper_resilience_stats - Get resilience and retry statistics

Usage Examples

Basic Report Execution

// Authenticate first
await jasper_authenticate({
  username: "jasperadmin",
  password: "jasperadmin"
});

// List available reports
const reports = await jasper_list_resources({
  folderUri: "/reports",
  resourceType: "reportUnit"
});

// Execute a report
const result = await jasper_run_report_sync({
  reportUri: "/reports/SampleReport",
  outputFormat: "pdf",
  parameters: {
    "StartDate": "2024-01-01",
    "EndDate": "2024-12-31"
  }
});

Upload and Schedule Reports

// Upload a new report
await jasper_upload_resource({
  resourcePath: "/reports/MyReport",
  label: "My Custom Report",
  jrxmlContent: "<?xml version='1.0'?>...",
  resourceType: "reportUnit"
});

// Create a scheduled job
await jasper_create_job({
  label: "Daily Sales Report",
  reportUri: "/reports/MyReport",
  schedule: {
    type: "simple",
    recurrenceInterval: 1,
    recurrenceIntervalUnit: "DAY"
  },
  outputFormats: ["pdf", "xlsx"],
  recipients: ["[email protected]"]
});

Docker Support

Quick Start with Docker

# Build the image
docker build -t jasperreports-mcp-server .

# Run with environment file
docker run -p 3000:3000 --env-file .env jasperreports-mcp-server

# Or use docker-compose for development
docker-compose up --build

Docker Configuration

Use the provided config/mcp-docker.json for Docker-based MCP setup:

{
  "mcpServers": {
    "jasperreports-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "--network=host",
        "--env-file", ".env",
        "jasperreports-mcp-server"
      ]
    }
  }
}

Troubleshooting

Common Issues

Connection Refused

Verify JASPER_URL is correct and accessible
Check if JasperReports Server is running
Ensure network connectivity

Authentication Failed

Verify username and password
Check if the user account is enabled
Try different authentication methods (basic, login, argument)

SSL Certificate Errors

Set JASPER_SSL_VERIFY=false for development
Install proper SSL certificates for production
Use HTTP instead of HTTPS for local development

Tool Not Found

Ensure the MCP server is properly configured in your IDE
Check that the server is running and accessible
Verify environment variables are set correctly

Debug Mode

Enable debug logging for troubleshooting:

export JASPER_DEBUG_MODE=true
export LOG_LEVEL=debug

Health Checks

Use the built-in health check tools:

// Test basic connectivity
await jasper_test_connection();

// Comprehensive health check
await jasper_deep_health_check();

// Check specific components
await jasper_component_health({ component: "authentication" });

Documentation

License

GPL-3.0-or-later License - see LICENSE file for details.

Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (npm test)
Run linting (npm run lint:fix)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone and install
git clone https://github.com/mr-wolf-gb/jasperreports-mcp-server.git
cd jasperreports-mcp-server
npm install

# Run tests
npm test
npm run test:coverage

# Start development server
npm run dev

Support & Community

🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📚 Documentation: Full Documentation

Roadmap

Made with ❤️ by Mr-Wolf-GB for the JasperReports and MCP community

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/workflows		.github/workflows
config		config
docs		docs
examples		examples
k8s		k8s
scripts		scripts
src		src
test		test
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
Dockerfile.dev		Dockerfile.dev
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

License

mr-wolf-gb/jasperreports-mcp-server

Folders and files

Latest commit

History

Repository files navigation

JasperReports MCP Server

Features

IDE Integration

Cursor IDE

Kiro IDE

Windsurf IDE

Claude Desktop

Other MCP-Compatible IDEs

Quick Start

Local Development

Production Installation

Development

Project Structure

Available Scripts

Testing

Configuration

Environment Variables

Configuration Examples

Available MCP Tools

🔐 Authentication & Connection

📁 Resource Management

📊 Report Execution

⏰ Job Scheduling

🎛️ Input Controls & Parameters

👥 User & Role Management

🔒 Permissions & Security

🏢 Domain Management

🛠️ Utilities & Templates

📊 Health & Monitoring

Usage Examples

Basic Report Execution

Upload and Schedule Reports

Docker Support

Quick Start with Docker

Docker Configuration

Troubleshooting

Common Issues

Debug Mode

Health Checks

Documentation

License

Contributing

Development Setup

Support & Community

Roadmap

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages