Python构建MCP服务器完整教程：5步打造专属AI工具调用系统

2025-06-20 07:37:42 2 阅读

**模型控制协议（Model Control Protocol, MCP）**是一种专为实现AI代理与工具解耦而设计的通信协议，为AI驱动应用程序的开发提供了高度的灵活性和模块化架构。通过MCP服务器，AI代理能够动态发现并调用各种工具来响应用户请求。本文将详细介绍MCP服务器的构建过程，包括工具函数的注册、配置以及与Claude Desktop等AI代理的集成。我们将使用Python语言结合Anthropic的mcp库来构建一个功能完整的通用MCP服务器。

MCP协议概述

MCP协议建立了AI代理与MCP服务器上托管工具集之间的标准化通信机制。当用户向AI代理提交查询时，代理会从MCP服务器获取可用的工具列表，将这些工具转换为AI模型可理解的格式，并与用户请求一同发送给底层的AI模型。AI模型根据请求内容和可用工具，决定调用哪个工具并返回相应的执行指令。这种解耦架构确保了AI代理与工具之间的独立性，不仅提升了系统的灵活性，还显著增强了整体架构的可扩展性。

开发环境准备

在开始MCP服务器开发之前，需要确保开发环境满足以下要求：

系统需要安装Python 3.8或更高版本。对于包管理，建议使用pip、Poetry或UV等现代化工具，本文将采用UV作为主要的包管理工具。还需要准备一个支持MCP协议的AI代理应用程序（如Claude Desktop）用于后续的功能测试。开发者还应具备Python编程和JSON数据格式的基础知识。

创建项目的过程非常简单，通过UV命令即可快速初始化：

 uv init McpAgent  
 cd McpAgent

该命令会生成一个针对Python开发优化的项目结构。项目根目录下包含Git仓库配置、gitignore文件用于忽略临时文件、python-version文件指定Python版本、main.py作为应用程序的入口点、pyproject.toml管理项目元数据和依赖关系、README.md提供项目文档，以及uv.lock文件确保依赖版本的一致性。

UV工具的优势在于其能够提供一致的依赖管理和虚拟环境创建功能，确保项目在不同系统环境中的可移植性。

工具函数的设计与实现

MCP服务器的核心功能依赖于工具函数的实现。我们首先创建一个用于获取系统信息的工具函数，该函数将作为MCP服务器托管的基础工具。

以下是一个完整的系统信息获取工具的实现示例：

tools.py

 import platform  
import json  

def get_host_info() -> str:  
    """  
    获取当前设备的系统信息。
      
    Returns:  
        str: 包含操作系统、架构等系统信息的JSON格式字符串。
    """  
    system_info = {  
        "os": platform.system(),  
        "architecture": platform.machine(),  
        "platform": platform.platform()  
    }  
    return json.dumps(system_info)  

if __name__ == "__main__":  
     print(get_host_info())

在设计工具函数时，需要遵循几个重要的原则。首先，函数命名应该具有明确的描述性，参数设计要清晰明了。例如，

get_host_info

这个函数名直接表达了其获取主机信息的功能。其次，完整的类型提示（如

-> str

）对于帮助AI模型理解函数的输入输出特征至关重要。

文档字符串的编写同样重要，特别是当函数功能不能从名称直接推断时，详细的文档字符串能够帮助AI模型更好地理解工具的用途和行为。在返回值设计方面，工具函数应该返回AI模型能够有效处理的字符串格式数据，通常采用JSON格式。在本例中，我们使用

json.dumps

方法将Python字典转换为JSON字符串。

工具函数的测试可以通过UV命令直接执行：

 uv run tools.py

正常情况下，该命令会输出类似以下的系统信息：

 {  
   "os": "Darwin",   
   "architecture": "arm64",   
   "platform": "macOS-15.4.1-arm64-arm-64bit"  
 }

MCP服务器的构建与配置

完成工具函数开发后，下一步是使用Anthropic的mcp库构建MCP服务器。该服务器将负责托管

get_host_info

工具并为AI代理提供访问接口。

首先需要安装mcp库。在使用UV的环境中，可以通过以下命令完成安装：

 uv add mcp

安装完成后，pyproject.toml文件会自动更新相关配置：

 [project]  
name = "mcpagent"  
version = "0.1.0"  
description = "Add your description here"  
readme = "README.md"  
requires-python = ">=3.12"  
dependencies = [  
    "mcp>=1.9.1",  
 ]

接下来构建基础的MCP服务器代码：

main.py

 from mcp.server.fastmcp import FastMCP  
import tools  

# 创建MCP服务器实例
mcp = FastMCP("System Info Service")  

# 注册工具函数
mcp.add_tool(tools.get_host_info)  

# 以stdio模式启动MCP服务器
def main() -> None:  
    mcp.run("stdio")  

if __name__ == "__main__":  
     main()

代码的核心组件包括FastMCP类，它是mcp库的主要接口。构造函数接受一个服务名称参数，虽然名称选择相对自由，但建议使用具有描述性的名称。

add_tool

方法用于将工具函数注册到MCP服务器中，支持多次调用以注册多个工具。

run

方法负责启动MCP服务器，其中mode参数指定通信模式。

MCP协议支持两种主要的通信模式：stdio模式使用标准输入输出进行本地通信，实现简单但要求代理和服务器运行在同一设备上；SSE（Server-Sent Events）模式通过HTTP协议实现通信，适合云端部署场景，但需要处理身份验证和授权机制。考虑到教学目的，本文采用stdio模式以降低复杂性。

对于工具函数与MCP服务器定义在同一文件中的情况，可以采用装饰器模式进行注册：

main.py

 from mcp.server.fastmcp import FastMCP  
import platform  
import json  

mcp = FastMCP("System Info Service")  

@mcp.tool  
def get_host_info() -> str:  
    """  
    获取当前设备的系统信息。
      
    Returns:  
        str: 包含操作系统、架构等系统信息的JSON格式字符串。
    """  
    system_info = {  
        "os": platform.system(),  
        "architecture": platform.machine(),  
        "platform": platform.platform()  
    }  
    return json.dumps(system_info)  

 mcp.run(mode="stdio")

@mcp.tool

装饰器在功能上等同于

mcp.add_tool(get_host_info)

的调用，提供了更加简洁的代码组织方式。

AI代理的配置与集成

为了验证MCP服务器的功能，我们选择Claude Desktop作为测试平台。Claude Desktop是一个用户友好的AI代理应用程序，内置了对MCP协议的支持。需要注意的是，其他AI代理（如Cline）的配置过程基本相似。

Claude Desktop的配置过程包括以下步骤：

首先，在Claude Desktop中打开设置菜单，然后访问开发者设置选项。在开发者设置中，点击"编辑配置"按钮，系统会打开包含配置文件的目录。

在配置文件目录中，需要定位或创建MCP配置文件（通常命名为claude_desktop_config.json）。配置文件的核心内容是指定启动MCP服务器的命令和参数。由于我们使用UV作为包管理工具，配置文件的格式如下：

mcp_config.json

 {  
  "mcpServers": {  
    "hostInfoMcp": {  
      "command": "/ABSOLUTE/PATH/TO/UV/uv",  
      "args": [  
        "--directory",  
        "/ABSOLUTE/PATH/TO/MCPAgent/FOLDER/",  
        "run",  
        "main.py"  
      ]  
    }  
  }  
 }

配置文件中有几个关键点需要特别注意。command字段必须指向UV可执行文件的完整绝对路径，在macOS系统中通常是"/Users/username/.local/bin/uv"。同时，directory参数也必须使用项目的完整绝对路径，例如"/Users/username/projects/McpAgent"。

配置项的含义分别是：name字段应与FastMCP构造函数中提供的服务名称保持一致；command字段指定MCP服务器的启动命令；args字段包含命令执行所需的参数列表。

完成配置文件编辑后，需要保存文件并重启Claude Desktop使配置生效。