Docs & Usage Guide

Spring Initializr MCP Server

An MCP (Model Context Protocol) server that provides access to Spring Initializr functionality, allowing AI assistants to generate and download Spring Boot projects programmatically.

What is this?

This project implements an MCP server that wraps the Spring Initializr API, enabling AI assistants (like Claude) to create Spring Boot projects with custom configurations. Instead of manually visiting start.spring.io, you can now ask your AI assistant to generate projects with specific dependencies, Java versions, and project structures.

Features

Generate Spring Boot Projects: Create new Spring Boot projects with custom configurations
Flexible Configuration: Support for different project types (Maven/Gradle), languages (Java/Kotlin/Groovy), and Java versions
Dependency Management: Add popular Spring Boot dependencies automatically
Native Compilation: Fast startup times with GraalVM native compilation
Cross-Platform: Native binaries available for Linux, Windows, and macOS (x64 and ARM64)
Automatic Extraction: Optional extraction of downloaded ZIP files
Dynamic Metadata: Automatically fetches latest Spring Boot versions and dependencies

Supported Parameters

When generating a project, you can specify:

Project Type: maven-project, gradle-project, gradle-project-kotlin
Language: java, kotlin, groovy
Java Version: 17, 21, 24 (defaults to 17)
Packaging: jar, war (defaults to jar)
Dependencies: Hundreds of Spring Boot starters and dependencies
Project Metadata: Group ID, Artifact ID, name, description, package name
Download Options: Custom download location and automatic ZIP extraction

Installation

Download Pre-built Binaries

Download the appropriate binary for your platform from the Releases page:

Linux x64: springinitializr-mcp-linux-x64
Windows x64: springinitializr-mcp-windows-x64.exe
macOS x64: springinitializr-mcp-macos-x64
macOS ARM64: springinitializr-mcp-macos-arm64

Build from Source

Requirements:

Java 24
GraalVM (for native compilation)

git clone https://github.com/hpalma/springinitializr-mcp.git
cd springinitializr-mcp
./gradlew build
./gradlew nativeCompile

Usage with Claude Desktop

Add the MCP server to your Claude Desktop configuration:

macOS/Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "springinitializr": {
      "command": "/path/to/springinitializr-mcp-binary"
    }
  }
}

Windows

Edit %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "springinitializr": {
      "command": "C:\\path\\to\\springinitializr-mcp-windows-x64.exe"
    }
  }
}

Example Usage

Once configured, you can ask Claude to generate Spring Boot projects:

"Create a Spring Boot web application with Spring Data JPA, PostgreSQL, and Spring Security dependencies"

"Generate a Kotlin Spring Boot project using Gradle with WebFlux and MongoDB"

"Create a Maven-based Spring Boot project with Thymeleaf, Validation, and Actuator"

The tool will generate and download the project as a ZIP file to your specified location, with optional automatic extraction.

Available Dependencies

The server supports all Spring Initializr dependencies, including:

Web: Spring Web, WebFlux, GraphQL, REST repositories
Security: Spring Security, OAuth2, LDAP
Data: JPA, JDBC, MongoDB, Redis, Elasticsearch, R2DBC
Messaging: RabbitMQ, Apache Kafka, WebSocket
Cloud: Spring Cloud Gateway, Config, Eureka, Feign
Ops: Actuator, Micrometer, Distributed Tracing
AI: Spring AI with various model providers
Testing: TestContainers, Contract testing

The dependency list is automatically updated by fetching the latest metadata from Spring Initializr.

Development

Running in Development

# Run with dev profile for more logging
./gradlew bootRun --args='--spring.profiles.active=dev'

# Generate updated constants from Spring Initializr
./gradlew generateToolDescriptions

# Run tests
./gradlew test

# Run native tests
./gradlew nativeTest

Code Generation

The project uses a Gradle task to fetch the latest Spring Initializr metadata and generate constants for supported dependencies and Java versions:

./gradlew generateToolDescriptions

This ensures the tool always supports the latest Spring Boot versions and dependencies by:

Fetching metadata from https://start.spring.io/metadata/client
Generating SpringInitializrConstants.java with current dependencies
Updating supported Java versions and default values

Testing

The project includes comprehensive tests:

Unit Tests: Standard JUnit tests for core functionality
Integration Tests: Tests for the MCP protocol implementation
Native Tests: Validation that native compilation works correctly
URL Builder Tests: Validation of Spring Initializr URL construction

# Run all tests
./gradlew test nativeTest nativeIntegrationTest

# Run only unit tests
./gradlew test

# Run only native integration tests
./gradlew nativeIntegrationTest

Native Performance Testing

The integration tests include startup time validation to ensure native compilation provides expected performance benefits:

Native executable startup under 1 second
Full MCP protocol handshake validation
Tool discovery and invocation testing

CI/CD

The project uses GitHub Actions for:

Continuous Integration: Build and test on every push/PR
Release Automation: Create native binaries for all platforms
Multi-platform Support: Linux, Windows, macOS (x64 and ARM64)
Automated Testing: Unit, integration, and native tests

Release Process

Create a new release on GitHub or trigger workflow manually
Native binaries are automatically built for all platforms
Binaries are attached to the release for download

Configuration

Application Configuration

The server uses Spring Boot configuration with the following key properties:

spring:
  application:
    name: springinitializr-mcp
  ai:
    mcp:
      server:
        name: springinitializr
        version: 1.0.0

Environment Profiles

Default: Minimal logging for production use
Dev: Enhanced logging for development and debugging

API Reference

Tool: generate-spring-boot-project

Generates and downloads a Spring Boot project with the specified configuration.

Parameters:

downloadFolderPath (optional): Target download directory
shouldExtract (optional): Whether to extract the ZIP file
projectType (optional): Project build system type
language (optional): Programming language
groupId (optional): Maven/Gradle group identifier
artifactId (optional): Project artifact identifier
springBootVersion (optional): Spring Boot version to use
name (optional): Project display name
description (optional): Project description
packageName (optional): Base Java package name
packaging (optional): Packaging type (JAR/WAR)
javaVersion (optional): Target Java version
dependencies (optional): Comma-separated dependency list

Returns: Absolute path to the downloaded file or extracted directory

Contributing

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 (./gradlew test nativeTest)
Update generated constants if needed (./gradlew generateToolDescriptions)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Troubleshooting

Common Issues

Native executable fails to start:

Ensure you have the correct binary for your platform
Check that the binary has execute permissions on Unix systems
Verify no antivirus software is blocking execution

Project generation fails:

Check internet connectivity to Spring Initializr
Verify the specified dependencies are valid
Ensure the download directory exists and is writable

MCP connection issues:

Verify the Claude Desktop configuration is correct
Check that the binary path is absolute and valid
Restart Claude Desktop after configuration changes

Debug Mode

Run with the dev profile for enhanced logging:

./gradlew bootRun --args='--spring.profiles.active=dev'

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Spring Initializr - The underlying service for generating Spring Boot projects
Model Context Protocol - The protocol specification
Spring AI - MCP server framework support
GraalVM - Native compilation capabilities

Spring Initializr