my-mcp-stdio-server
Spring AI MCP Weather STDIO Server - A Spring Boot starter project demonstrating how to build a Model Context Protocol (MCP) server that provides weather-related tools
Documentation
Spring AI MCP Weather STDIO Server
A Spring Boot starter project demonstrating how to build a Model Context Protocol (MCP) server that provides weather-related tools using the National Weather Service (weather.gov) API. This project showcases the Spring AI MCP Server Boot Starter capabilities with STDIO transport implementation.
For more information, see the MCP Server Boot Starter reference documentation.
Prerequisites
- Java 17 or later
- Maven 3.6 or later
- Understanding of Spring Boot and Spring AI concepts
- (Optional) Claude Desktop for AI assistant integration
About Spring AI MCP Server Boot Starter
The `spring-ai-mcp-server-spring-boot-starter` provides:
- Automatic configuration of MCP server components
- Support for both synchronous and asynchronous operation modes
- STDIO transport layer implementation
- Flexible tool registration through Spring beans
- Change notification capabilities
Project Structure
About Spring AI MCP Server Boot Starter
The `spring-ai-mcp-server-spring-boot-starter` provides:
- Automatic configuration of MCP server components
- Support for both synchronous and asynchronous operation modes
- STDIO transport layer implementation
- Flexible tool registration through Spring beans
- Change notification capabilities
Project Structure
src/
├── main/
│ ├── java/
│ │ └── org/springframework/ai/mcp/sample/server/
│ │ ├── McpServerApplication.java # Main application class with tool registration
│ │ └── WeatherService.java # Weather service implementation with MCP tools
│ └── resources/
│ └── application.properties # Server and transport configuration
└── test/
└── java/
└── org/springframework/ai/mcp/sample/client/
└── ClientStdio.java # Test client implementationBuilding and Running
The server uses STDIO transport mode and is typically started automatically by the client. To build the server jar:
./mvnw clean install -DskipTestsTool Implementation
The project demonstrates how to implement and register MCP tools using Spring's dependency injection and auto-configuration:
@Service
public class WeatherService {
@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastBrazil(
double latitude, // Latitude coordinate
double longitude // Longitude coordinate
) {
// Implementation
}
@Tool(description = "Get weather alerts for a US state")
public String getAlerts(
String state // Two-letter US state code (e.g., CA, NY)
) {
// Implementation
}
}
@SpringBootApplication
public class McpServerApplication {
@Bean
public List weatherTools(WeatherService weatherService) {
return ToolCallbacks.from(weatherService);
}
}The auto-configuration automatically registers these tools with the MCP server. You can have multiple beans producing lists of ToolCallbacks, and the auto-configuration will merge them.
Available Tools
1. Weather Forecast Tool
@Tool(description = "Get weather forecast for a specific latitude/longitude")
public String getWeatherForecastBrazil(
double latitude, // Latitude coordinate
double longitude // Longitude coordinate
) {
// Returns detailed forecast including:
// - Temperature and unit
// - Wind speed and direction
// - Detailed forecast description
}
// Example usage:
CallToolResult forecast = client.callTool(
new CallToolRequest("getWeatherForecastBrazil",
Map.of(
"latitude", 47.6062, // Seattle coordinates
"longitude", -122.3321
)
)
);2. Weather Alerts Tool
@Tool(description = "Get weather alerts for a US state")
public String getAlerts(
String state // Two-letter US state code (e.g., CA, NY)
) {
// Returns active alerts including:
// - Event type
// - Affected area
// - Severity
// - Description
// - Safety instructions
}
// Example usage:
CallToolResult alerts = client.callTool(
new CallToolRequest("getAlerts",
Map.of("state", "NY")
)
);Client Integration
Java Client Example
Create MCP Client Manually
// Create server parameters
ServerParameters stdioParams = ServerParameters.builder("java")
.args("-Dspring.ai.mcp.server.transport=STDIO",
"-Dspring.main.web-application-type=none",
"-Dlogging.pattern.console=",
"-jar",
"target/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar")
.build();
// Initialize transport and client
var transport = new StdioClientTransport(stdioParams);
var client = McpClient.sync(transport).build();The ClientStdio.java demonstrates how to implement an MCP client manually.
For a better development experience, consider using the MCP Client Boot Starters. These starters enable auto-configuration of multiple STDIO and/or SSE connections to MCP servers. See the starter-default-client and starter-webflux-client projects for examples.
Use MCP Client Boot Starter
Use the starter-default-client to connect to the weather `starter-stdio-server`:
1. Follow the `starter-default-client` readme instructions to build a `mcp-starter-default-client-0.0.1-SNAPSHOT.jar` client application.
2. Run the client using the configuration file:
java -Dspring.ai.mcp.client.stdio.connections.server1.command=java \
-Dspring.ai.mcp.client.stdio.connections.server1.args=-jar,/Users/christiantzolov/Dev/projects/spring-ai-examples/model-context-protocol/weather/starter-stdio-server/target/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar \
-Dai.user.input='What is the weather in NY?' \
-Dlogging.pattern.console= \
-jar mcp-starter-default-client-0.0.1-SNAPSHOT.jarClaude Desktop Integration
To integrate with Claude Desktop, add the following configuration to your Claude Desktop settings:
{
"mcpServers": {
"spring-ai-mcp-weather": {
"command": "java",
"args": [
"-Dspring.ai.mcp.server.stdio=true",
"-Dspring.main.web-application-type=none",
"-Dlogging.pattern.console=",
"-jar",
"/absolute/path/to/my-mcp-stdio-server-0.0.1-SNAPSHOT.jar"
]
}
}
}Replace `/absolute/path/to/` with the actual path to your built jar file.
Configuration
Application Properties
All properties are prefixed with `spring.ai.mcp.server`:
# Required STDIO Configuration
spring.main.web-application-type=none
spring.main.banner-mode=off
logging.pattern.console=
# Server Configuration
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.name=my-weather-server
spring.ai.mcp.server.version=0.0.1
# SYNC or ASYNC
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true
# Optional file logging
logging.file.name=my-mcp-stdio-server.logKey Configuration Notes
1. STDIO Mode Requirements
2. Server Type
Additional Resources
Frequently asked questions
What is my-mcp-stdio-server?
my-mcp-stdio-server is Spring AI MCP Weather STDIO Server - A Spring Boot starter project demonstrating how to build a Model Context Protocol (MCP) server that provides weather-related tools
How do I install my-mcp-stdio-server?
Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.
Is my-mcp-stdio-server open source?
Yes — it is hosted on GitHub at https://github.com/cloud4java/my-mcp-stdio-server and has 1 stars.
Related MCP tools
The official Java SDK for Model Context Protocol servers and clients. Maintained in collaboration with Spring AI Trusted by 2800+ developers.
Plugin for JADX to integrate MCP server Java-based implementation. Trusted by 600+ developers. Trusted by 600+ developers.
🤖 The Semantic Engine for Model Context Protocol(MCP) Clients and AI Agents 🔥 Java-based implementation.
MCP Server for Ghidra Java-based implementation. Trusted by 6400+ developers. Trusted by 6400+ developers. Trusted by 6400+ developers.
A library for communication with a Minecraft client/server. Built for the Model Context Protocol to enhance AI capabilities. Java-based implementation.
🙌 OpenHands: Code Less, Make More for the Model Context Protocol. Enhance AI assistants with powerful integrations. Python-based implementation.
Run your own MCP server? See who uses it and what to fix.
Measure it with TrackMCP