快速入门
面向客户端开发者
开始构建你自己的客户端，该客户端可以与所有MCP服务端集成。
在本教程中，你将学习如何构建一个与MCP服务端连接的LLM驱动的聊天机器人客户端。建议你先完成服务端快速入门，该指南将引导你完成构建第一个服务端的基本步骤。
Python
系统要求
在开始之前，请确保你的系统满足以下要求：
- Mac或Windows电脑
- 已安装最新版本的Python
- 已安装最新版本的
uv
设置你的环境
首先，使用uv创建一个新的Python项目：
# 创建项目目录
uv init mcp-client
cd mcp-client
# 创建虚拟环境
uv venv
# 激活虚拟环境
# 在Windows上：
.venv\Scripts\activate
# 在Unix或MacOS上：
source .venv/bin/activate
# 安装所需的包
uv add mcp anthropic python-dotenv
# 删除样板文件
rm hello.py
# 创建我们的主文件
touch client.py设置你的API密钥
你需要从Anthropic控制台 获取一个Anthropic API密钥。
创建一个.env文件来存储它：
# 创建.env文件
touch .env将你的密钥添加到.env文件中：
ANTHROPIC_API_KEY=<your key here>将.env添加到你的.gitignore文件中：
echo ".env" >> .gitignore确保你妥善保管你的ANTHROPIC_API_KEY！
创建客户端
基本客户端结构
首先，让我们设置导入并创建基本的客户端类：
import asyncio
from typing import Optional
from contextlib import AsyncExitStack
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from anthropic import Anthropic
from dotenv import load_dotenv
load_dotenv() # 从.env加载环境变量
class MCPClient:
def __init__(self):
# 初始化会话和客户端对象
self.session: Optional[ClientSession] = None
self.exit_stack = AsyncExitStack()
self.anthropic = Anthropic()
# 方法将在这里添加服务端接管理
接下来，我们将实现连接到MCP服务端的方法：
async def connect_to_server(self, server_script_path: str):
"""连接到MCP服务端
参数:
server_script_path: 服务端脚本的路径（.py或.js）
"""
is_python = server_script_path.endswith('.py')
is_js = server_script_path.endswith('.js')
if not (is_python or is_js):
raise ValueError("服务端脚本必须是.py或.js文件")
command = "python" if is_python else "node"
server_params = StdioServerParameters(
command=command,
args=[server_script_path],
env=None
)
stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
self.stdio, self.write = stdio_transport
self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
await self.session.initialize()
# 列出可用的工具
response = await self.session.list_tools()
tools = response.tools
print("\n连接到服务端，可用工具:", [tool.name for tool in tools])查询处理逻辑
现在让我们添加处理查询和处理工具调用的核心功能：
async def process_query(self, query: str) -> str:
"""使用Claude和可用工具处理查询"""
messages = [
{
"role": "user",
"content": query
}
]
response = await self.session.list_tools()
available_tools = [{
"name": tool.name,
"description": tool.description,
"input_schema": tool.inputSchema
} for tool in response.tools]
# 初始Claude API调用
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
# 处理响应并处理工具调用
final_text = []
assistant_message_content = []
for content in response.content:
if content.type == 'text':
final_text.append(content.text)
assistant_message_content.append(content)
elif content.type == 'tool_use':
tool_name = content.name
tool_args = content.input
# 执行工具调用
result = await self.session.call_tool(tool_name, tool_args)
final_text.append(f"[调用工具 {tool_name} 使用参数 {tool_args}]")
assistant_message_content.append(content)
messages.append({
"role": "assistant",
"content": assistant_message_content
})
messages.append({
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": content.id,
"content": result.content
}
]
})
# 从Claude获取下一个响应
response = self.anthropic.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1000,
messages=messages,
tools=available_tools
)
final_text.append(response.content[0].text)
return "\n".join(final_text)交互式聊天界面
现在我们将添加聊天循环和清理功能：
async def chat_loop(self):
"""运行交互式聊天循环"""
print("\nMCP客户端已启动！")
print("输入你的查询或输入'quit'退出。")
while True:
try:
query = input("\n查询: ").strip()
if query.lower() == 'quit':
break
response = await self.process_query(query)
print("\n" + response)
except Exception as e:
print(f"\n错误: {str(e)}")
async def cleanup(self):
"""清理资源"""
await self.exit_stack.aclose()主入口点
最后，我们将添加主执行逻辑：
async def main():
if len(sys.argv) < 2:
print("用法: python client.py <path_to_server_script>")
sys.exit(1)
client = MCPClient()
try:
await client.connect_to_server(sys.argv[1])
await client.chat_loop()
finally:
await client.cleanup()
if __name__ == "__main__":
import sys
asyncio.run(main())你可以在这里 找到完整的client.py文件。
关键组件解释
1. 客户端初始化
MCPClient类初始化时会管理会话和API客户端- 使用
AsyncExitStack进行资源管理 - 配置Anthropic客户端以与Claude交互
2. 服务端连接
- 支持Python和Node.js服务端
- 验证服务端脚本类型
- 设置正确的通信通道
- 初始化会话并列出可用工具
3. 查询处理
- 维护对话上下文
- 处理Claude的响应和工具调用
- 管理Claude和工具之间的消息流
- 将结果组合成连贯的响应
4. 交互式界面
- 提供简单的命令行界面
- 处理用户输入并显示响应
- 包含基本的错误处理
- 允许优雅退出
5. 资源管理
- 正确清理资源
- 处理连接问题
- 优雅的关闭程序
常见自定义点
-
工具处理
- 修改
process_query()以处理特定工具类型 - 添加工具调用的自定义错误处理
- 实现工具特定的响应格式化
- 修改
-
响应处理
- 自定义工具结果的格式化方式
- 添加响应过滤或转换
- 实现自定义日志记录
-
用户界面
- 添加GUI或Web界面
- 实现丰富的控制台输出
- 添加命令历史记录或自动补全
运行客户端
要使用任何MCP服务端运行你的客户端：
uv run client.py path/to/server.py # Python服务端
uv run client.py path/to/build/index.js # Node服务端如果你正在继续服务端快速入门中的天气教程，你的命令可能类似于：python client.py .../weather/src/weather/server.py
客户端将：
- 连接到指定的服务端
- 列出可用工具
- 启动一个交互式聊天会话，你可以：
- 输入查询
- 查看工具执行
- 从Claude获取响应
以下是连接到服务端快速入门中的天气服务端时的示例：
工作原理
当你提交查询时：
- 客户端从服务端获取可用工具列表
- 你的查询与工具描述一起发送给Claude
- Claude决定使用哪些工具（如果有）
- 客户端通过服务端执行任何请求的工具调用
- 结果被发送回Claude
- Claude提供自然语言响应
- 响应显示给你
最佳实践
-
错误处理
- 始终在try-catch块中包装工具调用
- 提供有意义的错误消息
- 优雅地处理连接问题
-
资源管理
- 使用
AsyncExitStack进行正确的清理 - 完成后关闭连接
- 处理服务端断开连接
- 使用
-
安全性
- 将API密钥安全地存储在
.env中 - 验证服务端响应
- 谨慎处理工具权限
- 将API密钥安全地存储在
故障排除
服务端路径问题
- 仔细检查服务端脚本的路径是否正确
- 如果相对路径不起作用，请使用绝对路径
- 对于Windows用户，确保在路径中使用正斜杠（/）或转义的反斜杠（\）
- 验证服务端文件具有正确的扩展名（Python为.py，Node.js为.js）
正确路径用法的示例：
# 相对路径
uv run client.py ./server/weather.py
# 绝对路径
uv run client.py /Users/username/projects/mcp-server/weather.py
# Windows路径（两种格式都可以）
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py响应时间
- 第一个响应可能需要长达30秒才能返回
- 这是正常的，发生在以下情况时：
- 服务端初始化
- Claude处理查询
- 工具正在执行
- 后续响应通常更快
- 在初始等待期间不要中断进程
常见错误消息
如果你看到：
FileNotFoundError：检查你的服务端路径Connection refused：确保服务端正在运行且路径正确Tool execution failed：验证工具所需的环境变量是否已设置Timeout error：考虑增加客户端配置中的超时时间
下一步
最后更新于: