面向服务器开发者 - Model Context Protocol

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

我们将构建什么

许多 LLM 目前还没有获取天气预报和恶劣天气警报的能力。让我们使用 MCP 来解决这个问题！

我们将构建一个暴露两个工具的服务器：get-alerts 和 get-forecast。然后我们将把服务器连接到一个 MCP 宿主（在本例中是 Claude for Desktop）：

服务器可以连接到任何客户端。我们在此选择 Claude for Desktop 是为了简单起见，但我们也有构建自己的客户端的指南以及其他客户端列表。

为什么选择 Claude for Desktop 而不是 Claude.ai？

MCP 核心概念

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

资源（Resources）：客户端可以读取的类文件数据（如 API 响应或文件内容）
工具（Tools）：可以由 LLM 调用的函数（需要用户批准）
提示（Prompts）：帮助用户完成特定任务的预设模板

本教程将主要关注工具。

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

预备知识

本快速入门假设您熟悉：

Python
像 Claude 这样的 LLM

系统要求

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

设置您的环境

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

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

确保之后重新启动终端，以确保 uv 命令被识别。

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

# 创建一个新目录用于我们的项目
uv init weather
cd weather

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate

# 安装依赖项
uv add "mcp[cli]" httpx

# 创建我们的服务器文件
touch weather.py

现在让我们开始构建您的服务器。

构建您的服务器

导入包并设置实例

将这些添加到 weather.py 的顶部：

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

# 初始化 FastMCP 服务器
mcp = FastMCP("weather")

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

FastMCP 类使用 Python 类型提示和文档字符串自动生成工具定义，使创建和维护 MCP 工具变得容易。

辅助函数

接下来，让我们添加用于查询和格式化来自国家气象局 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。为此，请在文本编辑器中打开 ~/Library/Application Support/Claude/claude_desktop_config.json 中的 Claude for Desktop 应用配置。如果文件不存在，请确保创建它。

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

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

然后，您将在 mcpServers 键中添加您的服务器。只有在至少一个服务器配置正确的情况下，Claude for Desktop 中的 MCP UI 元素才会显示。

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

Python

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

Python

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

Python

{
    "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。

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

预备知识

本快速入门假设您熟悉：

Python
像 Claude 这样的 LLM

系统要求

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

设置您的环境

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

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

确保之后重新启动终端，以确保 uv 命令被识别。

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

# 创建一个新目录用于我们的项目
uv init weather
cd weather

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate

# 安装依赖项
uv add "mcp[cli]" httpx

# 创建我们的服务器文件
touch weather.py

现在让我们开始构建您的服务器。

构建您的服务器

导入包并设置实例

将这些添加到 weather.py 的顶部：

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

# 初始化 FastMCP 服务器
mcp = FastMCP("weather")

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

FastMCP 类使用 Python 类型提示和文档字符串自动生成工具定义，使创建和维护 MCP 工具变得容易。

辅助函数

接下来，让我们添加用于查询和格式化来自国家气象局 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，请确保它已更新到最新版本。

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

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

然后，您将在 mcpServers 键中添加您的服务器。只有在至少一个服务器配置正确的情况下，Claude for Desktop 中的 MCP UI 元素才会显示。

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

Python

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

Python

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

Python

{
    "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。

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

预备知识

本快速入门假设您熟悉：

TypeScript
像 Claude 这样的 LLM

系统要求

对于 TypeScript，请确保已安装最新版本的 Node。

设置您的环境

首先，如果您尚未安装 Node.js 和 npm，请安装它们。您可以从 nodejs.org 下载它们。验证您的 Node.js 安装：

node --version
npm --version

对于本教程，您需要 Node.js 版本 16 或更高版本。

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

# 创建一个新目录用于我们的项目
mkdir weather
cd weather

# 初始化一个新的 npm 项目
npm init -y

# 安装依赖项
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

# 创建我们的文件
mkdir src
touch src/index.ts

更新您的 package.json 以添加 type: “module” 和一个构建脚本：

package.json

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

在项目根目录中创建一个 tsconfig.json：

tsconfig.json

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

现在让我们开始构建您的服务器。

构建您的服务器

导入包并设置实例

将这些添加到 src/index.ts 的顶部：

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";

// 创建服务器实例
const server = new McpServer({
  name: "weather",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

辅助函数

接下来，让我们添加用于查询和格式化来自国家气象局 API 数据的辅助函数：

// 用于发起 NWS API 请求的辅助函数
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;
  };
}

// 格式化警报数据
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[];
  };
}

实现工具执行

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

// 注册天气工具
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 }) => {
    // 获取网格点数据
    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",
          },
        ],
      };
    }

    // 获取预测数据
    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",
          },
        ],
      };
    }

    // 格式化预测期
    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,
        },
      ],
    };
  },
);

运行服务器

最后，实现运行服务器的主函数：

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);
});

确保运行 npm run build 以构建您的服务器！这是使您的服务器连接的非常重要的一步。

现在让我们从现有的 MCP 宿主 Claude for Desktop 测试您的服务器。

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

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

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

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

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

然后，您将在 mcpServers 键中添加您的服务器。只有在至少一个服务器配置正确的情况下，Claude for Desktop 中的 MCP UI 元素才会显示。

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

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

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

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

这告诉 Claude for Desktop：

有一个名为“weather”的 MCP 服务器
通过运行 node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js 启动它

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

这是一个基于 Spring AI MCP 自动配置和启动器的快速入门演示。要了解如何手动创建同步和异步 MCP 服务器，请参阅 Java SDK Server 文档。

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

更多信息，请参阅 MCP Server Boot Starter 参考文档。对于手动 MCP 服务器实现，请参阅 MCP Server Java SDK 文档。

系统要求

安装 Java 17 或更高版本。
Spring Boot 3.3.x 或更高版本

设置您的环境

使用 Spring Initializer 启动项目。

您需要添加以下依赖项：

<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>

<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>

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

然后通过设置应用程序属性来配置您的应用程序：

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

服务器配置属性文档记录了所有可用的属性。

现在让我们开始构建您的服务器。

构建您的服务器

天气服务

让我们实现一个 WeatherService.java，它使用 REST 客户端查询来自国家气象局 API 的数据：

@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
  }

  // ......
}

@Service 注解将自动注册服务到您的应用程序上下文中。 Spring AI @Tool 注解使创建和维护 MCP 工具变得容易。

自动配置将自动将这些工具注册到 MCP 服务器。

创建您的 Boot 应用程序

@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();
	}
}

使用 MethodToolCallbackProvider 工具将 @Tools 转换为 MCP 服务器使用的可操作回调。

运行服务器

最后，让我们构建服务器：

./mvnw clean install

这将在 target 文件夹中生成一个 mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar 文件。

现在让我们从现有的 MCP 宿主 Claude for Desktop 测试您的服务器。

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

Claude for Desktop 尚未在 Linux 上可用。

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

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

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

然后，您将在 mcpServers 键中添加您的服务器。只有在至少一个服务器配置正确的情况下，Claude for Desktop 中的 MCP UI 元素才会显示。

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

java

{
  "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

{
  "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

{
  "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"
      ]
    }
  }
}

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

这告诉 Claude for Desktop：

有一个名为“my-weather-server”的 MCP 服务器
通过运行 java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar 启动它

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

使用 Java 客户端测试您的服务器

手动创建 MCP 客户端

使用 McpClient 连接到服务器：

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();

使用 MCP 客户端启动器

使用 spring-ai-starter-mcp-client 依赖项创建一个新的启动器应用程序：

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

并将 spring.ai.mcp.client.stdio.servers-configuration 属性设置为指向您的 claude_desktop_config.json。您可以重用现有的 Anthropic Desktop 配置：

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

当您启动客户端应用程序时，自动配置将自动从 claude_desktop_config.json 创建 MCP 客户端。

更多信息，请参阅 MCP 客户端启动器参考文档。

构建您的服务器

设置实例

添加一个服务器初始化函数：

// 运行 MCP 服务器的主函数
fun `run mcp server`() {
    // 创建具有基本实现的 MCP 服务器实例
    val server = Server(
        Implementation(
            name = "weather", // 工具名称为“weather”
            version = "1.0.0" // 实现版本
        ),
        ServerOptions(
            capabilities = ServerCapabilities(tools = ServerCapabilities.Tools(listChanged = true))
        )
    )

    // 创建一个使用标准 IO 进行服务器通信的传输
    val transport = StdioServerTransport(
        System.`in`.asInput(),
        System.out.asSink().buffered()
    )

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

天气 API 辅助函数

接下来，让我们添加用于查询和转换来自国家气象局 API 响应的函数和数据类：

// 扩展函数，用于获取给定纬度和经度的天气预报信息
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()
    }
}

// 扩展函数，用于获取给定州的天气警报
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?,
    )
}

实现工具执行

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

// 创建一个具有默认请求配置和 JSON 内容协商的 HTTP 客户端
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)
    }
    // 安装内容协商插件，用于 JSON 序列化/反序列化
    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
}

// 注册一个工具以按州获取天气警报
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) })
}

// 注册一个工具以按纬度和经度获取天气预报
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) })
}

运行服务器

最后，实现运行服务器的主函数：

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

确保运行 ./gradlew build 以构建您的服务器。这是使您的服务器连接的非常重要的一步。

现在让我们从现有的 MCP 宿主 Claude for Desktop 测试您的服务器。

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

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

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

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

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

然后，您将在 mcpServers 键中添加您的服务器。只有在至少一个服务器配置正确的情况下，Claude for Desktop 中的 MCP UI 元素才会显示。

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

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

这告诉 Claude for Desktop：

有一个名为“weather”的 MCP 服务器
通过运行 java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar 启动它

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

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

预备知识

本快速入门假设您熟悉：

C#
LLMs like Claude
.NET 8 或更高版本

系统要求

安装 .NET 8 SDK 或更高版本。

设置您的环境

首先，让我们安装 dotnet，如果您尚未安装。您可以从官方 Microsoft .NET 网站下载 dotnet。验证您的 dotnet 安装：

dotnet --version

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

# 创建一个新目录用于我们的项目
mkdir weather
cd weather
# 初始化一个新的 C# 项目
dotnet new console

运行 dotnet new console 后，您将看到一个新的 C# 项目。您可以在您喜欢的 IDE 中打开该项目，例如 Visual Studio 或 Rider。或者，您可以使用 Visual Studio 项目向导创建一个 C# 应用程序。创建项目后，添加 Model Context Protocol SDK 和托管的 NuGet 包：

# 添加 Model Context Protocol SDK NuGet 包
dotnet add package ModelContextProtocol --prerelease
# 添加 .NET Hosting NuGet 包
dotnet add package Microsoft.Extensions.Hosting

现在让我们开始构建您的服务器。

构建您的服务器

打开项目中的 Program.cs 文件，并将其内容替换为以下代码：

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();

创建 ApplicationHostBuilder 时，请确保使用 CreateEmptyApplicationBuilder 而不是 CreateDefaultBuilder。这确保服务器不会向控制台写入任何其他消息。这仅适用于使用 STDIO 传输的服务器。

此代码设置了一个使用 Model Context Protocol SDK 创建 MCP 服务器的基本控制台应用程序，使用标准 I/O 传输。

天气 API 辅助函数

接下来，定义一个类，其中包含用于查询和转换来自国家气象局 API 响应的工具执行处理程序：

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()}
                """));
    }
}

运行服务器

最后，使用以下命令运行服务器：

dotnet run

这将启动服务器并监听标准输入/输出上的传入请求。

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

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

首先，确保您已安装 Claude for Desktop。您可以在此处安装最新版本。如果您已经有 Claude for Desktop，请确保它已更新到最新版本。 我们需要为您想要使用的 MCP 服务器配置 Claude for Desktop。为此，请在文本编辑器中打开 ~/Library/Application Support/Claude/claude_desktop_config.json 中的 Claude for Desktop 应用配置。如果文件不存在，请确保创建它。例如，如果您已安装 VS Code：

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

然后，您将在 mcpServers 键中添加您的服务器。只有在至少一个服务器配置正确的情况下，Claude for Desktop 中的 MCP UI 元素才会显示。在这种情况下，我们将添加我们的单个天气服务器，如下所示：

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

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

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

这告诉 Claude for Desktop：

有一个名为“weather”的 MCP 服务器
通过运行 dotnet run /ABSOLUTE/PATH/TO/PROJECT 启动它保存文件，并重新启动 Claude for Desktop。

测试命令

让我们确保 Claude for Desktop 能够识别我们在 weather 服务器中暴露的两个工具。您可以通过查找锤子图标来确认：

点击锤子图标后，您应该能看到列出的两个工具：

如果您的服务器未被 Claude for Desktop 识别，请参阅故障排除部分获取调试提示。

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

沙加缅度的天气如何？
德克萨斯州有哪些活动的天气警报？

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

幕后发生了什么

当您提出问题时：

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

故障排除

Claude for Desktop 集成问题

获取 Claude for Desktop 的日志

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

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

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

# 检查 Claude 的错误日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

服务器未在 Claude 中显示

检查 claude_desktop_config.json 文件语法
确保项目路径是绝对路径而不是相对路径
完全重启 Claude for Desktop

工具调用静默失败

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

检查 Claude 的错误日志
验证您的服务器构建和运行是否没有错误
尝试重启 Claude for Desktop

这些都不起作用，我该怎么办？

请参考我们的调试指南获取更好的调试工具和更详细的指导。

天气 API 问题

要获取更高级的故障排除信息，请查看我们的调试 MCP指南

下一步

构建客户端

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

示例服务器

查看我们的官方 MCP 服务器和实现示例

调试指南

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

使用 LLM 构建 MCP

学习如何使用像 Claude 这样的 LLM 来加速您的 MCP 开发

开始使用

教程

概念

开发

​我们将构建什么

​MCP 核心概念

​预备知识

​系统要求

​设置您的环境

​构建您的服务器

​导入包并设置实例

​辅助函数

​实现工具执行

​运行服务器

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

​预备知识

​系统要求

​设置您的环境

​构建您的服务器

​导入包并设置实例

​辅助函数

​实现工具执行

​运行服务器

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

​预备知识

​系统要求

​设置您的环境

​构建您的服务器

​导入包并设置实例

​辅助函数

​实现工具执行

​运行服务器

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

​系统要求

​设置您的环境

​构建您的服务器

​天气服务

​创建您的 Boot 应用程序

​运行服务器

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

​使用 Java 客户端测试您的服务器

​手动创建 MCP 客户端

​使用 MCP 客户端启动器

​更多 Java MCP 服务器示例

​预备知识

​系统要求

​设置您的环境

​构建您的服务器

​设置实例

​天气 API 辅助函数

​实现工具执行

​运行服务器

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

​预备知识

​系统要求

​设置您的环境

​构建您的服务器

​天气 API 辅助函数

​运行服务器

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

​测试命令

​幕后发生了什么

​故障排除

​下一步

构建客户端

示例服务器

调试指南

使用 LLM 构建 MCP

我们将构建什么

MCP 核心概念

预备知识

系统要求

设置您的环境

构建您的服务器

导入包并设置实例

辅助函数

实现工具执行

运行服务器

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

预备知识

系统要求

设置您的环境

构建您的服务器

导入包并设置实例

辅助函数

实现工具执行

运行服务器

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

预备知识

系统要求

设置您的环境

构建您的服务器

导入包并设置实例

辅助函数

实现工具执行

运行服务器

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

系统要求

设置您的环境

构建您的服务器

天气服务

创建您的 Boot 应用程序

运行服务器

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

使用 Java 客户端测试您的服务器

手动创建 MCP 客户端

使用 MCP 客户端启动器

更多 Java MCP 服务器示例

预备知识

系统要求

设置您的环境

构建您的服务器

设置实例

天气 API 辅助函数

实现工具执行

运行服务器

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

预备知识

系统要求

设置您的环境

构建您的服务器

天气 API 辅助函数

运行服务器

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

测试命令

幕后发生了什么

故障排除

下一步