What is Spring Mcp Bridge

Spring MCP Bridge is a tool that automatically converts REST endpoints from Spring Boot applications into an MCP (Message Conversation Protocol) server, enabling AI assistants like Claude and Cursor to directly interact with your APIs.

Use cases

Use cases include enabling AI assistants to interact with existing APIs without manual coding, automating customer support interactions, and integrating various AI tools with backend services.

How to use

To use Spring MCP Bridge, clone the repository, scan your Spring Boot project using the provided Python script, and run the generated MCP server. Finally, connect your MCP client to the server’s endpoint.

Key features

Key features include automatic scanning of REST endpoints, zero configuration required for existing Spring Boot code, preservation of request and response models, Javadoc extraction for enhanced descriptions, and complete documentation generation.

Where to use

Spring MCP Bridge is suitable for applications that require integration between Spring Boot APIs and AI assistants, particularly in fields like customer service, automation, and any domain utilizing conversational AI.

Spring MCP Bridge

Spring MCP Bridge is a tool that automatically converts REST endpoints from Spring Boot applications into an MCP (Message Conversation Protocol) server, allowing AI assistants like Claude, Cursor, and other MCP-compatible tools to directly interact with your APIs.

*It does not currently include authentication. If your Spring Boot API requires authentication, you will need to modify the handler code to include the appropriate headers or tokens.

📖 Overview

Integrating existing APIs with AI assistants typically requires manual coding or complex configuration. Spring MCP Bridge eliminates this complexity by automatically scanning your Spring Boot project and generating a ready-to-use MCP server.

✨ Features

• Automatic Scanning: Discovers all REST endpoints (@RestController, @GetMapping, etc.)
• Zero Configuration: No modifications needed to existing Spring Boot code
• Model Preservation: Maintains request and response models as MCP tools
• Javadoc Extraction: Uses existing documentation to enhance MCP tool descriptions
• Complete Documentation: Generates README and clear instructions for use

🚀 Installation

# Clone the repository
git clone https://github.com/brunosantos/spring-mcp-bridge.git

# Enter the directory
cd spring-mcp-bridge

🛠️ Usage

1. Scan your Spring Boot project:

python spring_boot_mcp_converter.py --project /path/to/spring-project --output ./mcp_server --name MyAPI

2. Run the generated MCP server:

cd mcp_server
pip install -r requirements.txt
python main.py

3. Connect via MCP client:
   • Configure your MCP client (Claude, Cursor, etc.) to use http://localhost:8000
   • The MCP schema will be available at http://localhost:8000/.well-known/mcp-schema.json

📋 Arguments

💻 Example

python spring_mcp_bridge.py --project ~/projects/my-spring-api --output ./mcp_server --name MyAPI

The tool will:

1. Scan the Spring Boot project for REST controllers
2. Identify model types, parameters, and return types
3. Generate a fully functional MCP server in Python/FastAPI
4. Create a compatible MCP schema that describes all endpoints

🔄 How It Works

1. Scanning: Analyzes Java source code to extract metadata from REST endpoints
2. Conversion: Converts Java types to JSON Schema types for MCP compatibility
3. Generation: Creates a FastAPI application that maps MCP calls to Spring REST calls
4. Forwarding: Routes requests from MCP client to the Spring Boot application

🔍 Spring Boot Features Supported

• REST Controllers (@RestController, @Controller)
• HTTP Methods (@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping)
• Request Parameters (@RequestParam)
• Path Variables (@PathVariable)
• Request Bodies (@RequestBody)
• Java Models and DTOs

⚙️ Configuration

The generated MCP server can be configured by editing the main.py file:

# The Spring Boot base URL - modify this to match your target API
SPRING_BASE_URL = "http://localhost:8080"

🧪 Testing

To test the MCP server:

1. Ensure your Spring Boot application is running
2. Start the MCP server
3. Visit http://localhost:8000/docs to see the FastAPI documentation
4. Check the MCP schema at http://localhost:8000/.well-known/mcp-schema.json
5. Connect with an MCP client like Claude

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

👨‍💻 Author

Bruno Santos

🙏 Acknowledgments

• Inspired by FastAPI-MCP and the growing ecosystem of MCP-compatible tools
• Thanks to the Spring Boot and FastAPI communities