使用 FastMCP 构建你的第一个 MCP 服务：从零开始的 Python 示例

简介

MCP（Multi-Client Protocol）是一种用于构建可扩展服务的通信协议框架。本文将以 FastMCP 库为核心，通过一个简单的「打招呼」服务示例，手把手教你如何搭建一个支持 Streamable HTTP 传输协议的 MCP 服务端与客户端。代码已通过 Python 3.10+ 验证。

---

环境准备

1. 安装依赖库：

pip install fastmcp

2. 确保本地环境支持异步编程（Python 3.7+）。

---

服务端实现（server.py）

核心代码解析

from fastmcp import FastMCP

# 初始化 MCP 服务实例
mcp = FastMCP(name="MyServer")

# 定义一个工具函数
@mcp.tool
def greet(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    # 启动服务（Streamable HTTP 模式）
    mcp.run(transport="streamable-http", host="127.0.0.1", port=9000)

代码详解

1. 服务初始化
   FastMCP(name="MyServer") 创建了一个名为 MyServer 的 MCP 服务实例。

2. 工具注册
   使用 @mcp.tool 装饰器将 greet 函数注册为 MCP 工具，客户端可通过该工具名调用服务。

3. 服务启动
   mcp.run() 方法以 Streamable HTTP 协议启动服务，监听本机 9000 端口。

---

客户端实现（client.py）

核心代码解析

import asyncio
from fastmcp import Client

# 配置 MCP 服务器地址
config = {
    "mcpServers": {
        "printer": {
            "url": "http://127.0.0.1:9000/mcp",
            "transport": "streamable-http"
        }
    }
}

# 初始化客户端
client = Client(config)

async def main():
    async with client:
        # 调用服务端工具
        greet_data = await client.call_tool("greet", {"name": "world"})
        print(f"greet: {greet_data}")

if __name__ == "__main__":
    asyncio.run(main())

代码详解

1. 客户端配置
   config 字典定义了 MCP 服务的连接信息，包含 URL 和传输协议。

2. 异步连接管理
   使用 async with client: 自动管理连接生命周期，确保资源释放。

3. 工具调用
   client.call_tool("greet", {"name": "world"}) 调用服务端的 greet 工具，传递参数 {name: "world"}。

---

运行效果

步骤 1：启动服务端

python server.py

输出（服务端日志）：

INFO: MyServer started on http://127.0.0.1:9000/mcp

步骤 2：运行客户端

python client.py

输出结果：

greet: Hello, world!

---

扩展方向

1. 多服务集成
   在客户端配置中可添加多个 MCP 服务地址，实现分布式调用。
2. 协议切换
   尝试替换 transport="stdio" 或 transport="websocket" 验证其他传输协议。
3. 工具参数验证
   为 greet 函数添加类型检查或默认值逻辑增强健壮性。

---

常见问题

Q1: 为什么客户端提示 Connection refused？

• 确保服务端已启动；
• 检查防火墙是否开放 9000 端口；
• 确认 URL 地址格式是否正确（需包含 /mcp 路径）。

Q2: 如何调试工具调用？

• 在服务端工具函数中添加日志打印；
• 使用 curl http://127.0.0.1:9000/mcp 验证 HTTP 接口可达性。

---

结语

通过本文，你已掌握了使用 FastMCP 构建基础 MCP 服务的核心方法。下一步可尝试集成 JSON Schema 参数校验、实现流式响应，或探索 MCP 协议的高级特性。实践是学习的最佳途径——试着用这个框架构建你的第一个微服务吧！

server.py

# my_server.py
from fastmcp import FastMCP

mcp = FastMCP(name="MyServer")


@mcp.tool
def greet(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"


if __name__ == "__main__":
    # This runs the server, defaulting to STDIO transport
    mcp.run(transport="streamable-http", host="127.0.0.1", port=9000)

    # To use a different transport, e.g., HTTP:
    # mcp.run(transport="streamable-http", host="127.0.0.1", port=9000)

client.py

import asyncio

from fastmcp import Client

# Create a standard MCP configuration with multiple servers
config = {
    "mcpServers": {
        # A local MCP server
        "printer": {
            "url": "http://127.0.0.1:9000/mcp",
            "transport": "streamable-http"
        }

    }
}

# Create a client that connects to both servers
client = Client(config)


async def main():
    async with client:
        # Access tools from different servers with prefixes
        greet_data = await client.call_tool("greet", {"name": "word"})

        print(f"greet: {greet_data}")


if __name__ == "__main__":
    asyncio.run(main())

https://gofastmcp.com/clients/client