MCP Client 开发教程

快速入门

面向客户端开发者

开始构建你自己的客户端，该客户端可以与所有MCP服务端集成。

在本教程中，你将学习如何构建一个与MCP服务端连接的LLM驱动的聊天机器人客户端。建议你先完成服务端快速入门，该指南将引导你完成构建第一个服务端的基本步骤。

Python 教程其他语言看这里

你可以在这里找到本教程的完整代码。

系统要求

在开始之前，请确保你的系统满足以下要求：

Mac或Windows电脑
已安装最新版本的Python
已安装最新版本的uv

设置你的环境

首先，使用uv创建一个新的Python项目：

bash 复制代码

# 创建项目目录
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文件来存储它：

bash 复制代码

# 创建.env文件
touch .env

将你的密钥添加到.env文件中：

bash 复制代码

ANTHROPIC_API_KEY=<your key here>

将.env添加到你的.gitignore文件中：

bash 复制代码

echo ".env" >> .gitignore

确保你妥善保管你的ANTHROPIC_API_KEY！

创建客户端

基本客户端结构

首先，让我们设置导入并创建基本的客户端类：

python 复制代码

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服务端的方法：

python 复制代码

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

查询处理逻辑

现在让我们添加处理查询和处理工具调用的核心功能：

python 复制代码

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)

交互式聊天界面

现在我们将添加聊天循环和清理功能：

python 复制代码

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

主入口点

最后，我们将添加主执行逻辑：

python 复制代码

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服务端运行你的客户端：

bash 复制代码

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中
- 验证服务端响应
- 谨慎处理工具权限

故障排除

服务端路径问题

仔细检查服务端脚本的路径是否正确
如果相对路径不起作用，请使用绝对路径
对于Windows用户，确保在路径中使用正斜杠（/）或转义的反斜杠（\）
验证服务端文件具有正确的扩展名（Python为.py，Node.js为.js）

正确路径用法的示例：

bash 复制代码

# 相对路径
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：考虑增加客户端配置中的超时时间

下一步

服务端示例

查看我们的官方MCP服务端和实现。这些示例展示了如何使用MCP构建各种类型的服务端，并提供了完整的代码和配置说明。你可以通过这些示例快速上手，并根据自己的需求进行定制。

客户端示例

查看支持MCP集成的客户端列表。这些客户端可以帮助你轻松连接到MCP服务端，并与LLM（如Claude）进行交互。无论是命令行工具还是图形界面，这些客户端都提供了丰富的功能和灵活的配置选项。

使用LLM构建MCP

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

核心架构

了解MCP如何连接客户端、服务端和LLM。通过深入理解MCP的核心架构，你可以更好地设计和管理你的MCP应用，确保系统的高效运行和扩展性。

MCP Client 开发教程

快速入门

面向客户端开发者

Python 教程 其他语言看这里

系统要求

设置你的环境

设置你的API密钥

创建客户端

基本客户端结构

服务端接管理

查询处理逻辑

交互式聊天界面

主入口点

关键组件解释

1. 客户端初始化

2. 服务端连接

3. 查询处理

4. 交互式界面

5. 资源管理

常见自定义点

运行客户端

工作原理

最佳实践

故障排除

服务端路径问题

响应时间

常见错误消息

下一步

Python 教程其他语言看这里