服务器开发者

在本教程中，我们将构建一个简单的 MCP 天气服务器并将其连接到主机，Claude for Desktop。我们将从基本设置开始，然后逐步进入更复杂的用例。

我们要构建的内容

许多 LLMs 目前无法获取天气预报和恶劣天气警报。让我们使用 MCP 来解决这个问题！

我们将构建一个服务器，提供两个工具：get-alerts 和 get-forecast。然后，我们将服务器连接到 MCP 主机（在这种情况下，是桌面版的 Claude）：

服务器可以连接到任何客户端。我们在这里选择了桌面版的 Claude 以简化操作，但我们也有关于构建您自己的客户端的指南以及其他客户端的列表。

核心 MCP 概念

MCP 服务器可以提供三种主要类型的功能：

资源 : 类似文件的数据，可以被客户端读取（如 API 响应或文件内容）
工具 : 可以被LLM调用的功能（需用户批准）
提示 : 帮助用户完成特定任务的预写模板

本教程将主要关注工具。

让我们开始构建我们的天气服务器吧！你可以在这里找到我们将要构建的完整代码。

前提知识

本快速入门假设您熟悉以下内容：

Python
LLMs like Claude

系统要求

已安装 Python 3.10 或更高版本。
您必须使用 Python MCP SDK 1.2.0 或更高版本。

设置你的环境

首先，我们来安装 uv 并设置 Python 项目和环境：

复制
curl -LsSf https://astral.sh/uv/install.sh | sh

确保之后重启您的终端，以保证 uv 命令能够被识别。

现在，让我们创建并设置我们的项目：

复制
# Create a new directory for our project
uv init weather
cd weather

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch weather.py

现在让我们深入构建你的服务器。

构建你的服务器

导入包并设置实例

将这些添加到你的 weather.py 文件的顶部:

复制
from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

FastMCP 类使用 Python 类型提示和文档字符串来自动生成工具定义，从而轻松创建和维护 MCP 工具。

辅助函数

接下来，让我们添加用于查询和格式化来自 National Weather Service API 的数据的辅助函数：

复制
async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

实现工具执行

工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：

复制
@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

运行服务器

最后，我们来初始化并运行服务器：

复制
if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

您的服务器已完成！运行 uv run weather.py 以确认一切正常工作。

现在让我们从现有的 MCP 主机测试你的服务器，Claude for Desktop。

使用 Claude for Desktop 测试您的服务器

Claude for Desktop 尚未在 Linux 上可用。Linux 用户可以继续阅读构建客户端教程，以构建一个连接到我们刚刚构建的服务器的 MCP 客户端。

首先，确保您已安装 Claude for Desktop。您可以在这里安装最新版本。如果您已经安装了 Claude for Desktop， 请确保它已更新到最新版本。

我们需要为你想使用的任何 MCP 服务器配置 Claude for Desktop。为此，请在文本编辑器中打开你的 Claude for Desktop 应用配置文件，位置在 ~/Library/Application Support/Claude/claude_desktop_config.json 。如果文件不存在，请确保创建该文件。

例如，如果您已经安装了 VS Code：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

然后你将把你的服务器添加到 mcpServers 键中。只有当至少一个服务器配置正确时，Claude for Desktop 中的 MCP 界面元素才会显示。

在这种情况下，我们将添加单个天气服务器，如下所示：

Python
复制
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

Python
Copy
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

Python
Copy
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
                "run",
                "weather.py"
            ]
        }
    }
}

您可能需要在 command 字段中填入 uv 可执行文件的完整路径。您可以通过在 MacOS/Linux 上运行 which uv 或在 Windows 上运行 where uv 来获取此路径。

确保你传入的是服务器的绝对路径。

这告诉 Claude for Desktop:

有一个名为“weather”的 MCP 服务器
通过运行 uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py 来启动它

保存文件，并重启 Claude for Desktop。

Let’s get started with building our weather server! You can find the complete code for what we’ll be building here.

Prerequisite knowledge

This quickstart assumes you have familiarity with:

Python
LLMs like Claude

System requirements

Python 3.10 or higher installed.
You must use the Python MCP SDK 1.2.0 or higher.

Set up your environment

First, let’s install uv and set up our Python project and environment:

Copy
curl -LsSf https://astral.sh/uv/install.sh | sh

Make sure to restart your terminal afterwards to ensure that the uv command gets picked up.

Now, let’s create and set up our project:

Copy
# Create a new directory for our project
uv init weather
cd weather

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch weather.py

Now let’s dive into building your server.

Building your server

Importing packages and setting up the instance

Add these to the top of your weather.py:

Copy
from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

The FastMCP class uses Python type hints and docstrings to automatically generate tool definitions, making it easy to create and maintain MCP tools.

Helper functions

Next, let’s add our helper functions for querying and formatting the data from the National Weather Service API:

Copy
async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

Implementing tool execution

The tool execution handler is responsible for actually executing the logic of each tool. Let’s add it:

Copy
@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

Running the server

Finally, let’s initialize and run the server:

Copy
if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

Your server is complete! Run uv run weather.py to confirm that everything’s working.

Let’s now test your server from an existing MCP host, Claude for Desktop.

Testing your server with Claude for Desktop

Claude for Desktop is not yet available on Linux. Linux users can proceed to the Building a client tutorial to build an MCP client that connects to the server we just built.

First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it’s updated to the latest version.

We’ll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at ~/Library/Application Support/Claude/claude_desktop_config.json in a text editor. Make sure to create the file if it doesn’t exist.

For example, if you have VS Code installed:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

You’ll then add your servers in the mcpServers key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.

In this case, we’ll add our single weather server like so:

Python
Copy
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

Python
Copy
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

Python
Copy
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
                "run",
                "weather.py"
            ]
        }
    }
}

You may need to put the full path to the uv executable in the command field. You can get this by running which uv on MacOS/Linux or where uv on Windows.

Make sure you pass in the absolute path to your server.

This tells Claude for Desktop:

There’s an MCP server named “weather”
To launch it by running uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py

Save the file, and restart Claude for Desktop.

Let’s get started with building our weather server! You can find the complete code for what we’ll be building here.

Prerequisite knowledge

This quickstart assumes you have familiarity with:

TypeScript
LLMs like Claude

System requirements

For TypeScript, make sure you have the latest version of Node installed.

Set up your environment

First, let’s install Node.js and npm if you haven’t already. You can download them from nodejs.org. Verify your Node.js installation:

Copy
node --version
npm --version

For this tutorial, you’ll need Node.js version 16 or higher.

Now, let’s create and set up our project:

Copy
# Create a new directory for our project
mkdir weather
cd weather

# Initialize a new npm project
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

# Create our files
mkdir src
touch src/index.ts

Update your package.json to add type: “module” and a build script:

package.json
Copy
{
  "type": "module",
  "bin": {
    "weather": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  },
  "files": [
    "build"
  ],
}

Create a tsconfig.json in the root of your project:

tsconfig.json
Copy
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Now let’s dive into building your server.

Building your server

Importing packages and setting up the instance

Add these to the top of your src/index.ts:

Copy
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";

// Create server instance
const server = new McpServer({
  name: "weather",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

Helper functions

Next, let’s add our helper functions for querying and formatting the data from the National Weather Service API:

Copy
// Helper function for making NWS API requests
async function makeNWSRequest<T>(url: string): Promise<T | null> {
  const headers = {
    "User-Agent": USER_AGENT,
    Accept: "application/geo+json",
  };

  try {
    const response = await fetch(url, { headers });
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return (await response.json()) as T;
  } catch (error) {
    console.error("Error making NWS request:", error);
    return null;
  }
}

interface AlertFeature {
  properties: {
    event?: string;
    areaDesc?: string;
    severity?: string;
    status?: string;
    headline?: string;
  };
}

// Format alert data
function formatAlert(feature: AlertFeature): string {
  const props = feature.properties;
  return [
    `Event: ${props.event || "Unknown"}`,
    `Area: ${props.areaDesc || "Unknown"}`,
    `Severity: ${props.severity || "Unknown"}`,
    `Status: ${props.status || "Unknown"}`,
    `Headline: ${props.headline || "No headline"}`,
    "---",
  ].join("\n");
}

interface ForecastPeriod {
  name?: string;
  temperature?: number;
  temperatureUnit?: string;
  windSpeed?: string;
  windDirection?: string;
  shortForecast?: string;
}

interface AlertsResponse {
  features: AlertFeature[];
}

interface PointsResponse {
  properties: {
    forecast?: string;
  };
}

interface ForecastResponse {
  properties: {
    periods: ForecastPeriod[];
  };
}

Implementing tool execution

The tool execution handler is responsible for actually executing the logic of each tool. Let’s add it:

Copy
// Register weather tools
server.tool(
  "get-alerts",
  "Get weather alerts for a state",
  {
    state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)"),
  },
  async ({ state }) => {
    const stateCode = state.toUpperCase();
    const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
    const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);

    if (!alertsData) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to retrieve alerts data",
          },
        ],
      };
    }

    const features = alertsData.features || [];
    if (features.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No active alerts for ${stateCode}`,
          },
        ],
      };
    }

    const formattedAlerts = features.map(formatAlert);
    const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`;

    return {
      content: [
        {
          type: "text",
          text: alertsText,
        },
      ],
    };
  },
);

server.tool(
  "get-forecast",
  "Get weather forecast for a location",
  {
    latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
    longitude: z.number().min(-180).max(180).describe("Longitude of the location"),
  },
  async ({ latitude, longitude }) => {
    // Get grid point data
    const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
    const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);

    if (!pointsData) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
          },
        ],
      };
    }

    const forecastUrl = pointsData.properties?.forecast;
    if (!forecastUrl) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to get forecast URL from grid point data",
          },
        ],
      };
    }

    // Get forecast data
    const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
    if (!forecastData) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to retrieve forecast data",
          },
        ],
      };
    }

    const periods = forecastData.properties?.periods || [];
    if (periods.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: "No forecast periods available",
          },
        ],
      };
    }

    // Format forecast periods
    const formattedForecast = periods.map((period: ForecastPeriod) =>
      [
        `${period.name || "Unknown"}:`,
        `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
        `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
        `${period.shortForecast || "No forecast available"}`,
        "---",
      ].join("\n"),
    );

    const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;

    return {
      content: [
        {
          type: "text",
          text: forecastText,
        },
      ],
    };
  },
);

Running the server

Finally, implement the main function to run the server:

Copy
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

Make sure to run npm run build to build your server! This is a very important step in getting your server to connect.

Let’s now test your server from an existing MCP host, Claude for Desktop.

Testing your server with Claude for Desktop

Claude for Desktop is not yet available on Linux. Linux users can proceed to the Building a client tutorial to build an MCP client that connects to the server we just built.

First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it’s updated to the latest version.

For example, if you have VS Code installed:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

You’ll then add your servers in the mcpServers key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.

In this case, we’ll add our single weather server like so:

Copy
{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
            ]
        }
    }
}

Copy
{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
            ]
        }
    }
}

Copy
{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": [
                "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"
            ]
        }
    }
}

This tells Claude for Desktop:

There’s an MCP server named “weather”
Launch it by running node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js

Save the file, and restart Claude for Desktop.

This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters. To learn how to create sync and async MCP Servers, manually, consult the Java SDK Server documentation.

Let’s get started with building our weather server! You can find the complete code for what we’ll be building here.

For more information, see the MCP Server Boot Starter reference documentation. For manual MCP Server implementation, refer to the MCP Server Java SDK documentation.

System requirements

Java 17 or higher installed.
Spring Boot 3.3.x or higher

Set up your environment

Use the Spring Initializer to bootstrap the project.

You will need to add the following dependencies:

Copy
<dependencies>
      <dependency>
          <groupId>org.springframework.ai</groupId>
          <artifactId>spring-ai-starter-mcp-server</artifactId>
      </dependency>

      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-web</artifactId>
      </dependency>
</dependencies>

Copy
<dependencies>
      <dependency>
          <groupId>org.springframework.ai</groupId>
          <artifactId>spring-ai-starter-mcp-server</artifactId>
      </dependency>

      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-web</artifactId>
      </dependency>
</dependencies>

Copy
dependencies {
  implementation platform("org.springframework.ai:spring-ai-starter-mcp-server")
  implementation platform("org.springframework:spring-web")   
}

Then configure your application by setting the application properties:

Copy
spring.main.bannerMode=off
logging.pattern.console=

The Server Configuration Properties documents all available properties.

Now let’s dive into building your server.

Building your server

Weather Service

Let’s implement a WeatherService.java that uses a REST client to query the data from the National Weather Service API:

Copy
@Service
public class WeatherService {

	private final RestClient restClient;

	public WeatherService() {
		this.restClient = RestClient.builder()
			.baseUrl("https://api.weather.gov")
			.defaultHeader("Accept", "application/geo+json")
			.defaultHeader("User-Agent", "WeatherApiClient/1.0 (your@email.com)")
			.build();
	}

  @Tool(description = "Get weather forecast for a specific latitude/longitude")
  public String getWeatherForecastByLocation(
      double latitude,   // Latitude coordinate
      double longitude   // Longitude coordinate
  ) {
      // Returns detailed forecast including:
      // - Temperature and unit
      // - Wind speed and direction
      // - Detailed forecast description
  }
	
  @Tool(description = "Get weather alerts for a US state")
  public String getAlerts(
      @ToolParam(description = "Two-letter US state code (e.g. CA, NY)" String state
  ) {
      // Returns active alerts including:
      // - Event type
      // - Affected area
      // - Severity
      // - Description
      // - Safety instructions
  }

  // ......
}

The @Service annotation with auto-register the service in your application context. The Spring AI @Tool annotation, making it easy to create and maintain MCP tools.

The auto-configuration will automatically register these tools with the MCP server.

Create your Boot Application

Copy
@SpringBootApplication
public class McpServerApplication {

	public static void main(String[] args) {
		SpringApplication.run(McpServerApplication.class, args);
	}

	@Bean
	public ToolCallbackProvider weatherTools(WeatherService weatherService) {
		return  MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
	}
}

Uses the the MethodToolCallbackProvider utils to convert the @Tools into actionable callbacks used by the MCP server.

Running the server

Finally, let’s build the server:

./mvnw clean install

This will generate a mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar file within the target folder.

Let’s now test your server from an existing MCP host, Claude for Desktop.

Testing your server with Claude for Desktop

Claude for Desktop is not yet available on Linux.

First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it’s updated to the latest version.

For example, if you have VS Code installed:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

You’ll then add your servers in the mcpServers key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.

In this case, we’ll add our single weather server like so:

java
Copy
{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-jar",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

java
Copy
{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-jar",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

java
Copy
{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.transport=STDIO",
        "-jar",
        "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather\\mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Make sure you pass in the absolute path to your server.

This tells Claude for Desktop:

There’s an MCP server named “my-weather-server”
To launch it by running java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar

Save the file, and restart Claude for Desktop.

Testing your server with Java client

Create a MCP Client manually

Use the McpClient to connect to the server:

Copy
var stdioParams = ServerParameters.builder("java")
  .args("-jar", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar")
  .build();

var stdioTransport = new StdioClientTransport(stdioParams);

var mcpClient = McpClient.sync(stdioTransport).build();

mcpClient.initialize();

ListToolsResult toolsList = mcpClient.listTools();

CallToolResult weather = mcpClient.callTool(
  new CallToolRequest("getWeatherForecastByLocation",
      Map.of("latitude", "47.6062", "longitude", "-122.3321")));

CallToolResult alert = mcpClient.callTool(
  new CallToolRequest("getAlerts", Map.of("state", "NY")));

mcpClient.closeGracefully();

Use MCP Client Boot Starter

Create a new boot starter application using the spring-ai-starter-mcp-client dependency:

Copy
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

and set the spring.ai.mcp.client.stdio.servers-configuration property to point to your claude_desktop_config.json. You can re-use the existing Anthropic Desktop configuration:

Copy
spring.ai.mcp.client.stdio.servers-configuration=file:PATH/TO/claude_desktop_config.json

When you start your client application, the auto-configuration will create, automatically MCP clients from the claude_desktop_config.json.

For more information, see the MCP Client Boot Starters reference documentation.

More Java MCP Server examples

The starter-webflux-server demonstrates how to create a MCP server using SSE transport. It showcases how to define and register MCP Tools, Resources, and Prompts, using the Spring Boot’s auto-configuration capabilities.

Let’s get started with building our weather server! You can find the complete code for what we’ll be building here.

Prerequisite knowledge

This quickstart assumes you have familiarity with:

Kotlin
LLMs like Claude

System requirements

Java 17 or higher installed.

Set up your environment

First, let’s install java and gradle if you haven’t already. You can download java from official Oracle JDK website. Verify your java installation:

java --version

Now, let’s create and set up your project:

Copy
# Create a new directory for our project
mkdir weather
cd weather

# Initialize a new kotlin project
gradle init

After running gradle init, you will be presented with options for creating your project. Select Application as the project type, Kotlin as the programming language, and Java 17 as the Java version.

Alternatively, you can create a Kotlin application using the IntelliJ IDEA project wizard.

After creating the project, add the following dependencies:

Copy
val mcpVersion = "0.4.0"
val slf4jVersion = "2.0.9"
val ktorVersion = "3.1.1"

dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
    implementation("org.slf4j:slf4j-nop:$slf4jVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
}

Also, add the following plugins to your build script:

Copy
plugins {
    kotlin("plugin.serialization") version "your_version_of_kotlin"
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

Now let’s dive into building your server.

Building your server

Setting up the instance

Add a server initialization function:

Copy
// Main function to run the MCP server
fun `run mcp server`() {
    // Create the MCP Server instance with a basic implementation
    val server = Server(
        Implementation(
            name = "weather", // Tool name is "weather"
            version = "1.0.0" // Version of the implementation
        ),
        ServerOptions(
            capabilities = ServerCapabilities(tools = ServerCapabilities.Tools(listChanged = true))
        )
    )

    // Create a transport using standard IO for server communication
    val transport = StdioServerTransport(
        System.`in`.asInput(),
        System.out.asSink().buffered()
    )

    runBlocking {
        server.connect(transport)
        val done = Job()
        server.onClose {
            done.complete()
        }
        done.join()
    }
}

Weather API helper functions

Next, let’s add functions and data classes for querying and converting responses from the National Weather Service API:

Copy
// Extension function to fetch forecast information for given latitude and longitude
suspend fun HttpClient.getForecast(latitude: Double, longitude: Double): List<String> {
    val points = this.get("/points/$latitude,$longitude").body<Points>()
    val forecast = this.get(points.properties.forecast).body<Forecast>()
    return forecast.properties.periods.map { period ->
        """
            ${period.name}:
            Temperature: ${period.temperature} ${period.temperatureUnit}
            Wind: ${period.windSpeed} ${period.windDirection}
            Forecast: ${period.detailedForecast}
        """.trimIndent()
    }
}

// Extension function to fetch weather alerts for a given state
suspend fun HttpClient.getAlerts(state: String): List<String> {
    val alerts = this.get("/alerts/active/area/$state").body<Alert>()
    return alerts.features.map { feature ->
        """
            Event: ${feature.properties.event}
            Area: ${feature.properties.areaDesc}
            Severity: ${feature.properties.severity}
            Description: ${feature.properties.description}
            Instruction: ${feature.properties.instruction}
        """.trimIndent()
    }
}

@Serializable
data class Points(
    val properties: Properties
) {
    @Serializable
    data class Properties(val forecast: String)
}

@Serializable
data class Forecast(
    val properties: Properties
) {
    @Serializable
    data class Properties(val periods: List<Period>)

    @Serializable
    data class Period(
        val number: Int, val name: String, val startTime: String, val endTime: String,
        val isDaytime: Boolean, val temperature: Int, val temperatureUnit: String,
        val temperatureTrend: String, val probabilityOfPrecipitation: JsonObject,
        val windSpeed: String, val windDirection: String,
        val shortForecast: String, val detailedForecast: String,
    )
}

@Serializable
data class Alert(
    val features: List<Feature>
) {
    @Serializable
    data class Feature(
        val properties: Properties
    )

    @Serializable
    data class Properties(
        val event: String, val areaDesc: String, val severity: String,
        val description: String, val instruction: String?,
    )
}

Implementing tool execution

The tool execution handler is responsible for actually executing the logic of each tool. Let’s add it:

Copy
// Create an HTTP client with a default request configuration and JSON content negotiation
val httpClient = HttpClient {
    defaultRequest {
        url("https://api.weather.gov")
        headers {
            append("Accept", "application/geo+json")
            append("User-Agent", "WeatherApiClient/1.0")
        }
        contentType(ContentType.Application.Json)
    }
    // Install content negotiation plugin for JSON serialization/deserialization
    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
}

// Register a tool to fetch weather alerts by state
server.addTool(
    name = "get_alerts",
    description = """
        Get weather alerts for a US state. Input is Two-letter US state code (e.g. CA, NY)
    """.trimIndent(),
    inputSchema = Tool.Input(
        properties = buildJsonObject {
            putJsonObject("state") {
                put("type", "string")
                put("description", "Two-letter US state code (e.g. CA, NY)")
            }
        },
        required = listOf("state")
    )
) { request ->
    val state = request.arguments["state"]?.jsonPrimitive?.content
    if (state == null) {
        return@addTool CallToolResult(
            content = listOf(TextContent("The 'state' parameter is required."))
        )
    }

    val alerts = httpClient.getAlerts(state)

    CallToolResult(content = alerts.map { TextContent(it) })
}

// Register a tool to fetch weather forecast by latitude and longitude
server.addTool(
    name = "get_forecast",
    description = """
        Get weather forecast for a specific latitude/longitude
    """.trimIndent(),
    inputSchema = Tool.Input(
        properties = buildJsonObject {
            putJsonObject("latitude") { put("type", "number") }
            putJsonObject("longitude") { put("type", "number") }
        },
        required = listOf("latitude", "longitude")
    )
) { request ->
    val latitude = request.arguments["latitude"]?.jsonPrimitive?.doubleOrNull
    val longitude = request.arguments["longitude"]?.jsonPrimitive?.doubleOrNull
    if (latitude == null || longitude == null) {
        return@addTool CallToolResult(
            content = listOf(TextContent("The 'latitude' and 'longitude' parameters are required."))
        )
    }

    val forecast = httpClient.getForecast(latitude, longitude)

    CallToolResult(content = forecast.map { TextContent(it) })
}

Running the server

Finally, implement the main function to run the server:

Copy
fun main() = `run mcp server`()

Make sure to run ./gradlew build to build your server. This is a very important step in getting your server to connect.

Let’s now test your server from an existing MCP host, Claude for Desktop.

Testing your server with Claude for Desktop

Claude for Desktop is not yet available on Linux. Linux users can proceed to the Building a client tutorial to build an MCP client that connects to the server we just built.

First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it’s updated to the latest version.

For example, if you have VS Code installed:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

You’ll then add your servers in the mcpServers key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.

In this case, we’ll add our single weather server like so:

Copy
{
    "mcpServers": {
        "weather": {
            "command": "java",
            "args": [
                "-jar",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar"
            ]
        }
    }
}

This tells Claude for Desktop:

There’s an MCP server named “weather”
Launch it by running java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar

Save the file, and restart Claude for Desktop.

Let’s get started with building our weather server! You can find the complete code for what we’ll be building here.

Prerequisite knowledge

This quickstart assumes you have familiarity with:

C#
LLMs like Claude
.NET 8 or higher

System requirements

.NET 8 SDK or higher installed.

Set up your environment

First, let’s install dotnet if you haven’t already. You can download dotnet from official Microsoft .NET website. Verify your dotnet installation:

dotnet --version

Now, let’s create and set up your project:

Copy
# Create a new directory for our project
mkdir weather
cd weather
# Initialize a new C# project
dotnet new console

After running dotnet new console, you will be presented with a new C# project. You can open the project in your favorite IDE, such as Visual Studio or Rider. Alternatively, you can create a C# application using the Visual Studio project wizard. After creating the project, add NuGet package for the Model Context Protocol SDK and hosting:

Copy
# Add the Model Context Protocol SDK NuGet package
dotnet add package ModelContextProtocol --prerelease
# Add the .NET Hosting NuGet package
dotnet add package Microsoft.Extensions.Hosting

Now let’s dive into building your server.

Building your server

Open the Program.cs file in your project and replace its contents with the following code:

Copy
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol;
using System.Net.Http.Headers;

var builder = Host.CreateEmptyApplicationBuilder(settings: null);

builder.Services.AddMcpServer()
    .WithStdioServerTransport()
    .WithToolsFromAssembly();

builder.Services.AddSingleton(_ =>
{
    var client = new HttpClient() { BaseAddress = new Uri("https://api.weather.gov") };
    client.DefaultRequestHeaders.UserAgent.Add(new ProductInfoHeaderValue("weather-tool", "1.0"));
    return client;
});

var app = builder.Build();

await app.RunAsync();

When creating the ApplicationHostBuilder, ensure you use CreateEmptyApplicationBuilder instead of CreateDefaultBuilder. This ensures that the server does not write any additional messages to the console. This is only neccessary for servers using STDIO transport.

This code sets up a basic console application that uses the Model Context Protocol SDK to create an MCP server with standard I/O transport.

Weather API helper functions

Next, define a class with the tool execution handlers for querying and converting responses from the National Weather Service API:

Copy
using ModelContextProtocol.Server;
using System.ComponentModel;
using System.Net.Http.Json;
using System.Text.Json;

namespace QuickstartWeatherServer.Tools;

[McpServerToolType]
public static class WeatherTools
{
    [McpServerTool, Description("Get weather alerts for a US state.")]
    public static async Task<string> GetAlerts(
        HttpClient client,
        [Description("The US state to get alerts for.")] string state)
    {
        var jsonElement = await client.GetFromJsonAsync<JsonElement>($"/alerts/active/area/{state}");
        var alerts = jsonElement.GetProperty("features").EnumerateArray();

        if (!alerts.Any())
        {
            return "No active alerts for this state.";
        }

        return string.Join("\n--\n", alerts.Select(alert =>
        {
            JsonElement properties = alert.GetProperty("properties");
            return $"""
                    Event: {properties.GetProperty("event").GetString()}
                    Area: {properties.GetProperty("areaDesc").GetString()}
                    Severity: {properties.GetProperty("severity").GetString()}
                    Description: {properties.GetProperty("description").GetString()}
                    Instruction: {properties.GetProperty("instruction").GetString()}
                    """;
        }));
    }

    [McpServerTool, Description("Get weather forecast for a location.")]
    public static async Task<string> GetForecast(
        HttpClient client,
        [Description("Latitude of the location.")] double latitude,
        [Description("Longitude of the location.")] double longitude)
    {
        var jsonElement = await client.GetFromJsonAsync<JsonElement>($"/points/{latitude},{longitude}");
        var periods = jsonElement.GetProperty("properties").GetProperty("periods").EnumerateArray();

        return string.Join("\n---\n", periods.Select(period => $"""
                {period.GetProperty("name").GetString()}
                Temperature: {period.GetProperty("temperature").GetInt32()}°F
                Wind: {period.GetProperty("windSpeed").GetString()} {period.GetProperty("windDirection").GetString()}
                Forecast: {period.GetProperty("detailedForecast").GetString()}
                """));
    }
}

Running the server

Finally, run the server using the following command:

dotnet run

This will start the server and listen for incoming requests on standard input/output.

Testing your server with Claude for Desktop

Claude for Desktop is not yet available on Linux. Linux users can proceed to the Building a client tutorial to build an MCP client that connects to the server we just built.

First, make sure you have Claude for Desktop installed. You can install the latest version here. If you already have Claude for Desktop, make sure it’s updated to the latest version. We’ll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at ~/Library/Application Support/Claude/claude_desktop_config.json in a text editor. Make sure to create the file if it doesn’t exist. For example, if you have VS Code installed:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

You’ll then add your servers in the mcpServers key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured. In this case, we’ll add our single weather server like so:

Copy
{
    "mcpServers": {
        "weather": {
            "command": "dotnet",
            "args": [
                "run",
                "--project",
                "/ABSOLUTE/PATH/TO/PROJECT",
                "--no-build"
            ]
        }
    }
}

Copy
{
    "mcpServers": {
        "weather": {
            "command": "dotnet",
            "args": [
                "run",
                "--project",
                "/ABSOLUTE/PATH/TO/PROJECT",
                "--no-build"
            ]
        }
    }
}

Copy
{
    "mcpServers": {
        "weather": {
            "command": "dotnet",
            "args": [
                "run",
                "--project",
                "C:\\ABSOLUTE\\PATH\\TO\\PROJECT",
                "--no-build"
            ]
        }
    }
}

This tells Claude for Desktop:

There’s an MCP server named “weather”
Launch it by running dotnet run /ABSOLUTE/PATH/TO/PROJECT Save the file, and restart Claude for Desktop.

使用命令进行测试

确保桌面版 Claude 识别到我们在 weather 服务器中公开的两个工具。您可以通过查找锤子图标来完成此操作：

点击锤子图标后，你应该会看到列出两个工具：

如果你的服务器没有被 Claude for Desktop 识别，请前往故障排除部分以获取调试建议。

如果锤子图标已经出现，您现在可以通过在 Claude for Desktop 中运行以下命令来测试您的服务器：

萨克拉门托的天气怎么样？
德克萨斯州有哪些活跃的天气警报？

由于这是美国国家气象服务，查询仅适用于美国地区。

“在背后发生了什么”

当你提出一个问题时：

客户端将你的问题发送给了 Claude
Claude 分析可用的工具并决定使用哪一个（些）
客户端通过 MCP 服务器执行选定的工具
结果被发送回 Claude
克劳德生成一个自然语言响应
响应已显示给您！

故障排查

从桌面版 Claude 获取日志

Claude.app 中与 MCP 相关的日志被写入到 ~/Library/Logs/Claude 目录下的日志文件中：

mcp.log 将包含有关 MCP 连接和连接失败的常规日志记录。
名为 mcp-server-SERVERNAME.log 的文件将包含来自指定服务器的错误（stderr）日志。

您可以运行以下命令来列出最近的日志并跟踪任何新的日志：

复制
# Check Claude's logs for errors
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

服务器未显示在 Claude 中

检查你的 claude_desktop_config.json 文件语法
确保你的项目路径是绝对路径，而不是相对路径
完全重启桌面版 Claude

工具调用失败且无提示

如果 Claude 尝试使用工具但它们失败了：

检查 Claude 的日志以查找错误
验证您的服务器构建并运行无误
尝试重新启动 Claude for Desktop

没有任何东西在工作。我该怎么办？

请参阅我们的 debugging guide 以获取更好的调试工具和更详细的指导。

要进行更高级的故障排除，请查看我们的指南：Debugging MCP

下一步

构建客户端

学习如何构建你自己的可以连接到你的服务器的 MCP 客户端

示例服务器

查看我们的官方 MCP 服务器和实现的图库

调试指南

学习如何有效地调试 MCP 服务器和集成

构建 MCP 与 LLMs

了解如何像 Claude 一样使用LLMs来加速你的 MCP 开发

开始使用

教程

概念

Development

​我们要构建的内容

​核心 MCP 概念

​前提知识

​系统要求

​设置你的环境

​构建你的服务器

​导入包并设置实例

​辅助函数

​实现工具执行

​运行服务器

​使用 Claude for Desktop 测试您的服务器

​Prerequisite knowledge

​System requirements

​Set up your environment

​Building your server

​Importing packages and setting up the instance

​Helper functions

​Implementing tool execution

​Running the server

​Testing your server with Claude for Desktop

​Prerequisite knowledge

​System requirements

​Set up your environment

​Building your server

​Importing packages and setting up the instance

​Helper functions

​Implementing tool execution

​Running the server

​Testing your server with Claude for Desktop

​System requirements

​Set up your environment

​Building your server

​Weather Service

​Create your Boot Application

​Running the server

​Testing your server with Claude for Desktop

​Testing your server with Java client

​Create a MCP Client manually

​Use MCP Client Boot Starter

​More Java MCP Server examples

​Prerequisite knowledge

​System requirements

​Set up your environment

​Building your server

​Setting up the instance

​Weather API helper functions

​Implementing tool execution

​Running the server

​Testing your server with Claude for Desktop

​Prerequisite knowledge

​System requirements

​Set up your environment

​Building your server

​Weather API helper functions

​Running the server

​Testing your server with Claude for Desktop

​使用命令进行测试

​“在背后发生了什么”

​故障排查

​下一步

构建客户端

示例服务器

调试指南

构建 MCP 与 LLMs

我们要构建的内容

核心 MCP 概念

前提知识

系统要求

设置你的环境

构建你的服务器

导入包并设置实例

辅助函数

实现工具执行

运行服务器

使用 Claude for Desktop 测试您的服务器

Prerequisite knowledge

System requirements

Set up your environment

Building your server

Importing packages and setting up the instance

Helper functions

Implementing tool execution

Running the server

Testing your server with Claude for Desktop

Prerequisite knowledge

System requirements

Set up your environment

Building your server

Importing packages and setting up the instance

Helper functions

Implementing tool execution

Running the server

Testing your server with Claude for Desktop

System requirements

Set up your environment

Building your server

Weather Service

Create your Boot Application

Running the server

Testing your server with Claude for Desktop

Testing your server with Java client

Create a MCP Client manually

Use MCP Client Boot Starter

More Java MCP Server examples

Prerequisite knowledge

System requirements

Set up your environment

Building your server

Setting up the instance

Weather API helper functions

Implementing tool execution

Running the server

Testing your server with Claude for Desktop

Prerequisite knowledge

System requirements

Set up your environment

Building your server

Weather API helper functions

Running the server

Testing your server with Claude for Desktop

使用命令进行测试

“在背后发生了什么”

故障排查

下一步