mcp-for-beginners 实战:用 TypeScript / Python / .NET / Java / Rust 编写你自己的 MCP 客户端
mcp-for-beginners 实战:用 TypeScript / Python / .NET / Java / Rust 编写你自己的 MCP 客户端
客户端(Client)是直接与 MCP 服务器通信、请求资源(Resources)、工具(Tools)与提示词(Prompts)的自定义应用或脚本。与依赖 Inspector 图形界面的交互方式不同,编写自有客户端意味着完全可编程、可自动化的交互,这让你可以把 MCP 能力嵌入到自己的工作流、自动化任务和定制解决方案中。本文以 mcp-for-beginners 课程第二章「Creating a client」为骨架,结合仓库内 TypeScript、Python、.NET、Java、Rust 五套语言的完整示例源码,从导入库、实例化客户端、列出服务器功能、调用功能到运行客户端逐步拆解,学完你将掌握编写并测试跨语言 MCP 客户端、驱动上一章构建的 MCP 服务器的完整能力。
概述与学习目标
本课在 Model Context Protocol(MCP)生态中引入「客户端」这一概念。课程目标是:
- 理解客户端能做什么;
- 编写你自己的客户端;
- 让客户端连接 MCP 服务器并完成测试,确认服务器行为符合预期。
上一章(01-first-server)已经教会你构建 MCP 服务器;本章则从「调用方」视角出发,让同一套服务器可以被你自己的程序驱动。
编写一个客户端需要做什么
从高层看,编写客户端要完成四件事:
- 导入正确的库:沿用与服务器相同语言的 MCP SDK,但使用不同的构造(客户端相关 API)。
- 实例化客户端:创建客户端实例,并把它连接到选定的传输(Transport)方式。
- 决定列出哪些功能:MCP 服务器自带资源、工具和提示词,你需要决定列出其中哪些。
- 把客户端集成到宿主应用:在了解服务器能力后,将其接入宿主应用,使得用户输入 prompt 或命令时能触发对应的服务器功能。
一个直观的 TypeScript 示例客户端(完整版见 solution/typescript/src/client.ts):
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "node",
args: ["server.js"]
});
const client = new Client(
{
name: "example-client",
version: "1.0.0"
}
);
await client.connect(transport);
// 列出提示词
const prompts = await client.listPrompts();
// 获取一个提示词
const prompt = await client.getPrompt({
name: "example-prompt",
arguments: { arg1: "value" }
});
// 列出资源
const resources = await client.listResources();
// 读取资源
const resource = await client.readResource({
uri: "file:///example.txt"
});
// 调用工具
const result = await client.callTool({
name: "example-tool",
arguments: { arg1: "value" }
});
这段代码做了三件事:导入库;创建客户端实例并通过 stdio 连接;列出并调用提示词、资源和工具。至此你就拥有一个能与 MCP 服务器对话的客户端。
练习:逐步编写客户端
下面按五个步骤逐段解释代码,你可以跟着一起写。
-1- 导入所需的库
我们需要客户端本身以及所选传输协议的引用。stdio 适合在本机运行的程序,SSE(Server-Sent Events)是另一种传输协议,将在后续章节介绍。本课以 stdio 为主线。
TypeScript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
Python
from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client
.NET
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Client;
Java
沿用上一章 01-first-server/solution/java 的 Java Spring Boot 工程结构,在 src/main/java/com/microsoft/mcp/sample/client/ 下新建 SDKClient 类并加入以下 imports(完整实现见 solution/java/src/main/java/com/microsoft/mcp/sample/client/SDKClient.java):
import java.util.Map;
import org.springframework.web.reactive.function.client.WebClient;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.spec.McpClientTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.ListToolsResult;
Rust
在 Cargo.toml 中加入依赖(仓库中 solution 实际使用的版本见 solution/rust/Cargo.toml,其中 rmcp 已升级到 2.x):
[package]
name = "calculator-client"
version = "0.1.0"
edition = "2024"
[dependencies]
rmcp = { version = "0.5.0", features = ["client", "transport-child-process"] }
serde_json = "1.0.141"
tokio = { version = "1.46.1", features = ["rt-multi-thread"] }
随后在客户端代码中导入必要库:
use rmcp::{
RmcpError,
model::CallToolRequestParam,
service::ServiceExt,
transport::{ConfigureCommandExt, TokioChildProcess},
};
use tokio::process::Command;
-2- 实例化客户端与传输
需要分别创建传输实例和客户端实例。
TypeScript
const transport = new StdioClientTransport({
command: "node",
args: ["server.js"]
});
const client = new Client(
{
name: "example-client",
version: "1.0.0"
}
);
await client.connect(transport);
这里的关键点:StdioClientTransport 通过 command 和 args 指定如何找到并启动服务器——客户端负责拉起子进程,因此必须给出服务器入口命令。Client 构造函数接收 { name, version } 作为客户端标识(MCP 协议要求每次连接携带客户端身份信息)。最后 connect(transport) 建立连接。仓库里的真实示例指向上一章的服务器:solution/typescript/src/client.ts 使用 command: "node", args: ["./build/index.js"]。
Python
from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client
# 为 stdio 连接创建服务器参数
server_params = StdioServerParameters(
command="mcp", # 可执行文件
args=["run", "server.py"], # 可选的命令行参数
env=None, # 可选的环境变量
)
async def run():
async with stdio_client(server_params) as (read, write):
async with ClientSession(
read, write
) as session:
# 初始化连接
await session.initialize()
if __name__ == "__main__":
import asyncio
asyncio.run(run())
这里:StdioServerParameters 用于描述如何启动服务器;stdio_client(server_params) 作为异步上下文管理器返回 (read, write) 流;ClientSession 在其上建立会话并调用 initialize() 完成协议握手。入口处将 run 交给 asyncio.run。对照 solution/python/client.py,初始化后还会继续列资源、列工具、读资源、调工具。
.NET
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using ModelContextProtocol.Client;
var builder = Host.CreateApplicationBuilder(args);
builder.Configuration
.AddEnvironmentVariables()
.AddUserSecrets<Program>();
var clientTransport = new StdioClientTransport(new()
{
Name = "Demo Server",
Command = "dotnet",
Arguments = ["run", "--project", "path/to/file.csproj"],
});
await using var mcpClient = await McpClient.CreateAsync(clientTransport);
这里创建了 stdio 传输并得到客户端 mcpClient,后续用它列出和调用服务器功能。注意 Arguments 既可以指向 *.csproj 也可以直接指向可执行文件。仓库中的 .NET 客户端(solution/dotnet/Program.cs)甚至直接以相对路径定位同目录 server/bin/Debug/net9.0/server 可执行文件,实现客户端与服务器的同一仓库内自启动。
Java
public class SDKClient {
public static void main(String[] args) {
var transport = new WebFluxSseClientTransport(WebClient.builder().baseUrl("http://localhost:8080"));
new SDKClient(transport).run();
}
private final McpClientTransport transport;
public SDKClient(McpClientTransport transport) {
this.transport = transport;
}
public void run() {
var client = McpClient.sync(this.transport).build();
client.initialize();
// 你的客户端逻辑写在这里
}
}
要点:main 方法设置指向 http://localhost:8080 的 SSE 传输(服务器将运行于此);客户端类以传输为构造参数;run() 中用 McpClient.sync(this.transport).build() 构建同步客户端并 initialize() 初始化连接。SSE 传输适合与 Java Spring Boot MCP 服务器进行 HTTP 通信。
Rust
该 Rust 客户端假定服务器是同一目录下的姊妹项目 calculator-server,以下代码会启动服务器并连接:
async fn main() -> Result<(), RmcpError> {
// 假定服务器是同一目录下名为 "calculator-server" 的姊妹项目
let server_dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.parent()
.expect("failed to locate workspace root")
.join("calculator-server");
let client = ()
.serve(
TokioChildProcess::new(Command::new("cargo").configure(|cmd| {
cmd.arg("run").current_dir(server_dir);
}))
.map_err(RmcpError::transport_creation::<TokioChildProcess>)?,
)
.await?;
// TODO: 初始化
// TODO: 列出工具
// TODO: 以 {"a": 3, "b": 2} 调用 add 工具
client.cancel().await?;
Ok(())
}
() .serve(...) 是 rmcp 的便捷启动模式,TokioChildProcess 负责把服务器作为子进程拉起并建立 stdio 通道,configure(|cmd| ...) 可定制子进程命令(cargo run + 工作目录)。注意仓库 solution 的 main.rs 实际上启动的是 dotnet run 的 .NET 服务器,并已把「初始化 / 列工具 / 调工具」三个 TODO 全部补齐。
-3- 列出服务器功能
现在客户端已能连接(在服务器运行的前提下),但还没有列出服务器能力,接下来做这件事。
TypeScript
// 列出提示词
const prompts = await client.listPrompts();
// 列出资源
const resources = await client.listResources();
// 列出工具
const tools = await client.listTools();
Python
# 列出可用资源
resources = await session.list_resources()
print("LISTING RESOURCES")
for resource in resources:
print("Resource: ", resource)
# 列出可用工具
tools = await session.list_tools()
print("LISTING TOOLS")
for tool in tools.tools:
print("Tool: ", tool.name)
Python 通过 list_resources() 与 list_tools() 列出资源与工具并打印。
.NET
foreach (var tool in await client.ListToolsAsync())
{
Console.WriteLine($"{tool.Name} ({tool.Description})");
}
上面展示了如何列出服务器工具,并对每个工具打印名称(及描述)。
Java
// 列出并展示工具
ListToolsResult toolsList = client.listTools();
System.out.println("Available Tools = " + toolsList);
// 你也可以 ping 服务器以确认连接
client.ping();
listTools() 获取服务器上全部工具;ping() 验证连接可用;ListToolsResult 包含所有工具的名称、描述和输入模式(schema)。仓库的 SDKClient.java 在 client.initialize() 后立即调用 client.ping() 再 listTools()。
Rust
在 main 函数中初始化客户端后,可以初始化服务器并列出部分能力:
// 初始化
let server_info = client.peer_info();
println!("Server info: {:?}", server_info);
// 列出工具
let tools = client.list_tools(Default::default()).await?;
println!("Available tools: {:?}", tools);
仓库的 main.rs 对 peer_info() 返回的服务器信息做了更完整的展示:服务器名、版本、协议版本、instructions 以及 tools / resources / prompts / completions / logging 等能力开关,并逐个打印工具名与描述。
到这一步我们已经掌握了全部功能清单。这个客户端比较简单——需要显式地按需调用功能。下一章(03-llm-client)会构建接入自有大语言模型 LLM 的进阶客户端。现在先看如何调用服务器功能。
-4- 调用功能
调用功能时,必须确保参数(arguments)正确,某些场景还要指定所调功能的名字。
TypeScript
// 读取资源
const resource = await client.readResource({
uri: "file:///example.txt"
});
// 调用工具
const result = await client.callTool({
name: "example-tool",
arguments: {
arg1: "value"
}
});
// 调用提示词
const promptResult = await client.getPrompt({
name: "review-code",
arguments: {
code: "console.log(\"Hello world\")"
}
})
-
读取资源:调用
readResource()并指定uri。服务器端大概是这样注册的:server.resource( "readFile", new ResourceTemplate("file://{name}", { list: undefined }), async (uri, { name }) => ({ contents: [{ uri: uri.href, text: `Hello, ${name}!` }] }) );客户端的
file://example.txt与服务器的file://{name}模板匹配,example.txt被映射为name参数。 -
调用工具:指定
name与arguments:const result = await client.callTool({ name: "example-tool", arguments: { arg1: "value" } }); -
获取提示词:以
name和arguments调用getPrompt()。服务器端声明如下:server.prompt( "review-code", { code: z.string() }, ({ code }) => ({ messages: [{ role: "user", content: { type: "text", text: `Please review this code:\n\n${code}` } }] }) );与之匹配的客户端调用即为:
const promptResult = await client.getPrompt({ name: "review-code", arguments: { code: "console.log(\"Hello world\")" } })
仓库 solution/typescript/src/index.ts 演示了同款三件套:add 工具、file://{path} 资源模板、review-code 提示词,可作为「服务器对侧」的参照。
Python
# 读取资源
print("READING RESOURCE")
content, mime_type = await session.read_resource("greeting://hello")
# 调用工具
print("CALL TOOL")
result = await session.call_tool("add", arguments={"a": 1, "b": 7})
print(result.content)
read_resource("greeting://hello") 读取名为 greeting 的资源;call_tool("add", arguments={...}) 调用 add 工具。配套服务器 solution/python/server.py 用 @mcp.resource("greeting://{name}") 和 @mcp.tool() 分别声明了这两者。
.NET
- 调用工具:
var result = await mcpClient.CallToolAsync(
"Add",
new Dictionary<string, object?>() { ["a"] = 1, ["b"] = 3 },
cancellationToken:CancellationToken.None);
- 打印结果:
Console.WriteLine(result.Content.First(c => c.Type == "text").Text);
// Sum 4
仓库 solution/dotnet/Program.cs 的调用形式类似(工具名 "add",参数 {"a": 1, "b": 3}),并用 ((TextContentBlock)result.Content[0]).Text 提取文本结果。
Java
// 调用各种计算器工具
CallToolResult resultAdd = client.callTool(new CallToolRequest("add", Map.of("a", 5.0, "b", 3.0)));
System.out.println("Add Result = " + resultAdd);
CallToolResult resultSubtract = client.callTool(new CallToolRequest("subtract", Map.of("a", 10.0, "b", 4.0)));
System.out.println("Subtract Result = " + resultSubtract);
CallToolResult resultMultiply = client.callTool(new CallToolRequest("multiply", Map.of("a", 6.0, "b", 7.0)));
System.out.println("Multiply Result = " + resultMultiply);
CallToolResult resultDivide = client.callTool(new CallToolRequest("divide", Map.of("a", 20.0, "b", 4.0)));
System.out.println("Divide Result = " + resultDivide);
CallToolResult resultHelp = client.callTool(new CallToolRequest("help", Map.of()));
System.out.println("Help = " + resultHelp);
- 用
callTool()+CallToolRequest调用多个计算工具; - 每次调用指定工具名和工具所需的
Map参数; - 服务器工具期望具体的参数名(如数学运算的 "a"、"b");
- 结果以
CallToolResult返回,包含服务器响应。
仓库的 SDKClient.java 还额外调用了 power、squareRoot、absolute 等工具,并在结束时 client.closeGracefully() 优雅关闭。
Rust
// 以 {"a": 3, "b": 2} 调用 add 工具
let a = 3;
let b = 2;
let tool_result = client
.call_tool(CallToolRequestParam {
name: "add".into(),
arguments: serde_json::json!({ "a": a, "b": b }).as_object().cloned(),
})
.await?;
println!("Result of {:?} + {:?}: {:?}", a, b, tool_result);
CallToolRequestParam 携带工具名与参数,参数用 serde_json::json! 构造;仓库 main.rs 还会解析返回内容中的文本块、检查 is_error 标志并打印友好的结果信息。
-5- 运行客户端
在终端执行以下命令:
TypeScript——在 package.json 的 scripts 中添加如下条目:
"client": "tsc && node build/client.js"
npm run client
Python
python client.py
.NET
dotnet run
Java——先确保 MCP 服务器运行在 http://localhost:8080,再运行客户端:
# 构建项目
./mvnw clean compile
# 运行客户端
./mvnw exec:java -Dexec.mainClass="com.microsoft.mcp.sample.client.SDKClient"
也可以直接运行 solution/java 提供的完整客户端工程:
# 进入 solution 目录
cd 03-GettingStarted/02-client/solution/java
# 构建并运行 JAR
./mvnw clean package
java -jar target/calculator-client-0.0.1-SNAPSHOT.jar
Rust
cargo fmt
cargo run
作业:自己动手写一个客户端
本作业要求综合所学,独立创建一个客户端。下面是可供客户端调用的服务器示例,试试再给服务器加更多功能让它更有意思:
TypeScript
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
// 创建 MCP 服务器
const server = new McpServer({
name: "Demo",
version: "1.0.0"
});
// 添加加法工具
server.tool("add",
{ a: z.number(), b: z.number() },
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }]
})
);
// 添加动态问候资源
server.resource(
"greeting",
new ResourceTemplate("greeting://{name}", { list: undefined }),
async (uri, { name }) => ({
contents: [{
uri: uri.href,
text: `Hello, ${name}!`
}]
})
);
// 开始在 stdin 接收消息、在 stdout 发送消息
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("MCPServer started on stdin/stdout");
}
main().catch((error) => {
console.error("Fatal error: ", error);
process.exit(1);
});
Python
# server.py
from mcp.server.fastmcp import FastMCP
# 创建 MCP 服务器
mcp = FastMCP("Demo")
# 添加加法工具
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
# 添加动态问候资源
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
"""Get a personalized greeting"""
return f"Hello, {name}!"
.NET
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using ModelContextProtocol.Server;
using System.ComponentModel;
var builder = Host.CreateApplicationBuilder(args);
builder.Logging.AddConsole(consoleLogOptions =>
{
// 将所有日志配置到 stderr
consoleLogOptions.LogToStandardErrorThreshold = LogLevel.Trace;
});
builder.Services
.AddMcpServer()
.WithStdioServerTransport()
.WithToolsFromAssembly();
await builder.Build().RunAsync();
[McpServerToolType]
public static class CalculatorTool
{
[McpServerTool, Description("Adds two numbers")]
public static string Add(int a, int b) => $"Sum {a + b}";
}
Rust 方面,你在上一节已经学会了用 Rust 创建简单 MCP 服务器,可以在此基础上继续扩展。
解决方案与完整示例
解决方案目录结构
solution 目录包含完整、开箱即用的客户端实现,覆盖本教程全部概念,每个方案都同时包含客户端与服务器代码,按语言组织为独立、自洽的项目(详见 solution/README.md):
solution/
├── typescript/ # 基于 npm/Node.js 的 TypeScript 客户端
│ ├── package.json # 依赖与脚本
│ ├── tsconfig.json # TypeScript 配置
│ └── src/ # 源码(client.ts / index.ts)
├── java/ # Java Spring Boot 客户端工程
│ ├── pom.xml # Maven 配置
│ ├── src/ # Java 源码
│ └── mvnw # Maven wrapper
├── python/ # Python 客户端实现
│ ├── client.py # 主客户端代码
│ ├── server.py # 配套服务器
│ └── README.md # Python 专属说明
├── dotnet/ # .NET 客户端工程
│ ├── dotnet.csproj # 工程配置
│ ├── Program.cs # 主客户端代码
│ └── dotnet.sln # 解决方案文件
├── rust/ # Rust 客户端实现
│ ├── Cargo.lock # Cargo 锁定文件
│ ├── Cargo.toml # 工程配置与依赖
│ ├── src
│ │ └── main.rs # 主客户端代码
└── server/ # 附加的 .NET 服务器实现
├── Program.cs # 服务器代码
└── server.csproj # 服务器工程文件
每个语言方案都包含:教程中的全部客户端功能、正确的依赖与配置、构建/运行脚本、语言专属的详细 README,以及错误处理与结果处理示例。
运行步骤:进入首选语言目录(cd solution/typescript/、cd solution/java/、cd solution/python/、cd solution/dotnet/),按各目录 README 安装依赖、构建并运行客户端。预期输出大致如下:
Prompt: Please review this code: console.log("hello");
Resource template: file
Tool result: { content: [ { type: 'text', text: '9' } ] }
完整的单文件示例
仓库还在 03-GettingStarted/02-client 下提供了 5 个开箱即用、单文件的完整客户端实现:
| 语言 | 文件 | 说明 |
|---|---|---|
| Java | client_example_java.java | 使用 SSE 传输、带全面错误处理的完整 Java 客户端 |
| C# | client_example_csharp.cs | 使用 stdio 传输、自动启动服务器的完整 C# 客户端 |
| TypeScript | client_example_typescript.ts | 完整支持 MCP 协议的 TypeScript 客户端 |
| Python | client_example_python.py | 使用 async/await 模式的完整 Python 客户端 |
| Rust | client_example_rust.rs | 基于 Tokio 异步操作的完整 Rust 客户端 |
每个完整示例都包含:连接建立与错误处理、服务器发现(工具/资源/提示词)、计算器运算(add、subtract、multiply、divide、help)、结果处理与格式化输出、全面错误处理,以及带逐步注释的干净代码。例如 client_example_typescript.ts 的 extractTextResult() 专门从 { type: "text", text } 结构里抽取文本,并在无文本时回退到整段 JSON 序列化。
上手步骤:从上表选择语言 → 通读完整示例文件理解实现 → 按 complete_examples.md 运行 → 按需定制扩展。各语言在传输、服务器启动方式、异步模型与关键库上的差异一览:
| 语言 | 传输 | 服务器启动 | 异步模型 | 关键库 |
|---|---|---|---|---|
| Java | SSE/HTTP | 外部启动 | 同步 | WebFlux、MCP SDK |
| C# | Stdio | 自动 | Async/Await | .NET MCP SDK |
| TypeScript | Stdio | 自动 | Async/Await | Node MCP SDK |
| Python | Stdio | 自动 | asyncio | Python MCP SDK |
| Rust | Stdio | 自动 | Async/Await | Rust MCP SDK、Tokio |
solution 目录 vs 完整单文件示例:solution 提供带构建文件、依赖齐全、可立即运行的完整工程结构(更接近生产形态);完整示例则是单文件、聚焦的参考代码(便于跨语言对比学习)。两者各有价值——完整工程用于实战项目,单文件示例用于学习与参考。
本章要点
关于客户端的核心结论:
- 客户端既能发现服务器功能,也能调用服务器功能;
- 客户端可以在自身启动时同时拉起服务器(如本章所示),也可以连接已经运行中的服务器;
- 除了上一章介绍的 Inspector 之外,编写客户端是测试服务器能力的绝佳途径——可编程、可自动化、可嵌入自定义工作流。
相关示例与下一步
课程还提供了各语言的 Calculator 示例,可继续深入:Java Calculator、.NET Calculator、JavaScript Calculator、TypeScript Calculator、Python Calculator、Rust Calculator。
下一步:阅读创建带 LLM 的客户端,让客户端接入自己的大语言模型,实现更智能的 MCP 应用。