spring-ai -test

Showcases how to integrate Spring AI's support for MCP (Model Context Protocol) within Spring Boot applications, covering both server-side and client-side implementations.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio oalles-spring-ai-mcp-test docker run -i oalles/spring-ai-mcp-test:latest \
  --env MCP_LOG_LEVEL="info" \
  --env MCP_SERVER_PORT="8080"

How to use

This MCP server implementation exposes three components built with Spring AI: a Geocoder service (port 8081), a Timezone service (port 8082), and an MCP Host that coordinates tools and renders responses from an LLM via a console interface. The MCP Host uses the Geocoder and Timezone services to answer questions about city locations and their time zones, leveraging an LLM with TOOL support (in this project, a model like Llama3.2 via Ollama).

To use, run the provided services, then interact with the MCP Host to input city names. The host will use the Geocoder to fetch latitude/longitude, then the Timezone service to derive timezone information, presenting the results in a structured manner through the LLM-driven console interface. This setup demonstrates how to compose an MCP-enabled server that coordinates multiple data sources and provides a cohesive tool-assisted answer flow.

How to install

Prerequisites:

Java JDK 17+ and Maven
Ollama or equivalent model provider configured to run a model compatible with TOOL usage
Git to clone repository (or download the modules separately)

Installation steps:

Clone the repository or download the modules: git clone <repository-url> cd your-repo-root
Build and run the Geocoder service: cd geocoder mvn spring-boot:run
Build and run the Timezone service: cd ../timezone mvn spring-boot:run
Build and run the MCP Host: cd ../mcp-host mvn spring-boot:run

If you prefer containerized execution, ensure Docker is installed and pull the prebuilt image for the MCP test setup, then run: docker run -i oalles/spring-ai-mcp-test:latest

Note: Ensure your environment variables for model hosting (like Ollama) are configured as described in the project documentation.

Additional notes

Tips and considerations:

Ensure the Geocoder and Timezone services are reachable by the MCP Host (the default ports are 8081 and 8082, respectively).
The MCP Host console expects to interact with a model that supports TOOLS; verify your model provider (e.g., Ollama) is configured and running.
If you encounter connectivity issues, check that Docker networking allows the MCP Host to reach the Geocoder and Timezone services.
Adjust MCP logging via MCP_LOG_LEVEL to debug issues during development.
The npm_package field is null because this is a Java-based MCP server (Maven/Spring Boot) rather than an npm-based Node.js server.

Related MCP Servers

mcp-for-beginners

14.5k

This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.

xiaozhi-esp32 -java

1.1k

小智ESP32的Java企业级管理平台，提供设备监控、音色定制、角色切换和对话记录管理的前后端及服务端一体化解决方案

mcp-mianshiya

118

基于 Spring AI 的面试鸭搜索题目的 MCP Server 服务，快速让 AI 搜索企业面试真题和答案

api2mcp4j

This is a revolutionary AI MCP plugin with excellent pluggable and encapsulated features. With just a few lines of configuration, it can easily integrate into your Spring boot web program and give it MCP capabilities,inheriting the powerful engineering capabilities of the Spring series framework

spring-ai

From Java Dev to AI Engineer: Spring AI Fast Track

springboot-ai -example

Example Spring AI Model Context Protocol (MCP)