AI导哈

MCP客户端

一个用于Model Context Protocol (MCP)的最小化跨平台Python客户端，支持通过OpenAI调用MCP工具进行聊天和工具调用。

  • by HogRed
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 HogRed/mcp-client

使用说明

MCP客户端

一个最小的跨平台Python客户端 模型上下文协议（MCP）.

MCP是一种新兴的标准，用于将本地工具、数据和功能安全地暴露给AI模型。客户端在运行时协商服务器提供的内容（工具、提示、资源），而不是硬编码集成。这个存储库提供了一个紧凑、可读的握手示例，以及一个由OpenAI驱动的薄聊天层，可以决定何时调用服务器工具。

为何这很重要

现代人工智能工作流程越来越需要结构化地访问本地功能（查询文件、运行实用程序、生成特定于域的响应），而不会泄露任意的系统控制。MCP为此定义了一个许可词汇表。该项目显示：

  • 如何通过stdio以跨平台的方式启动MCP服务器（不需要POSIX shell）
  • 如何枚举和显示提供的功能（“成员”）
  • 如何让LLM通过OpenAI函数/工具调用来调用这些工具
  • 如何保持实施规模小，便于学习

高水位流量

CLI Args → MCPClient → Start server (stdio) → Initialize ClientSession
			↓
		List members (--members) OR Chat loop (--chat)
			↓
	  Chat handler → OpenAI model → (optional) tool calls → MCP tool execution
			↓
		Aggregated response printed to terminal

设计原则

  • 跨平台：避免贝壳；使用 sys.executable.
  • 最小表面：一个客户端类、一个示例服务器、一个用于工具感知聊天的处理程序。
  • 显式错误：如果缺少服务器脚本或API密钥，则会快速失败。
  • 教育：明确区分关注点(cli.py, mcp_client.py, handlers.py).

特性

  • 通过stdio（Windows/macOS/Linux）启动本地MCP服务器脚本
  • 列出服务器成员：工具、提示和资源
  • 可以使用OpenAI调用MCP工具的聊天模式
  • 通过以下方式清洁CLI界面 python -m mcp_client 或 mcp-client 控制台脚本

需求

  • Python 3.10+
  • mcp>=1.22.0
  • openai>=2.8.1
  • 一个OpenAI API密钥(OPENAI_API_KEY)

安装

使用 uv （推荐）：

# From the project root
uv pip install .

或与 pip:

pip install .

快速开始

设置OpenAI API密钥，然后针对包含的服务器运行客户端：

# Set for current PowerShell session
$env:OPENAI_API_KEY = "sk-..."

# List members
uv run python -m mcp_client mcp_server/mcp_server.py --members

# Chat mode (calls tools when appropriate)
uv run python -m mcp_client mcp_server/mcp_server.py --chat

或者，安装包后，使用控制台脚本（如果在PATH上）：

mcp-client mcp_server/mcp_server.py --members
mcp-client mcp_server/mcp_server.py --chat

Windows笔记

  • 本地venv的PowerShell激活： .\\.venv\\Scripts\\Activate.ps1
  • 使用时不需要激活venv uv run--它自动管理环境。

命令行界面

CLI支持：

  • --members：服务器公开的打印工具、提示和资源
  • --chat：启动一个简单的聊天循环，可以调用MCP工具

示例：

# Show help (module form)
uv run python -m mcp_client --help

# With console script (after install)
mcp-client --help

项目结构

main.py
pyproject.toml
mcp_client/
	__init__.py
	__main__.py
    chat.py
	cli.py
	handlers.py
	mcp_client.py
mcp_server/
	mcp_server.py
  • mcp_server/mcp_server.py：在stdio上运行的MCP服务器（FastMCP）示例
  • mcp_client/mcp_client.py：启动服务器并打开MCP会话的客户端
  • mcp_client/chat.py：Hanldes应用程序聊天循环
  • mcp_client/cli.py：分析CLI参数
  • mcp_client/handlers.py：集成OpenAI和MCP工具的聊天处理程序
  • mcp_client/__main__.py：CLI条目（模块形式）
  • pyproject.toml：包元数据和控制台脚本映射

配置

  • OPENAI_API_KEY 必须设置。选项：
    • 仅限会话： $env:OPENAI_API_KEY = "sk-..."
    • 为您的用户坚持： [System.Environment]::SetEnvironmentVariable('OPENAI_API_KEY', 'sk-...', 'User') （重新启动终端）

发展

在本地运行而不安装：

# Members
uv run python -m mcp_client mcp_server/mcp_server.py --members

# Chat
uv run python -m mcp_client mcp_server/mcp_server.py --chat

PowerShell中的可选venv激活：

.\\.venv\\Scripts\\Activate.ps1
# work with python/pip
deactivate

备注

  • 此客户端避免了POSIX shell依赖关系，并使用 sys.executable 启动服务器脚本以实现跨平台兼容性。
  • 如果你依赖于较新的打字功能（例如。， typing.Self)，使用Python 3.11+或添加 typing-extensions.

引用

此项目从以下位置获取基础代码 构建Python MCP客户端以从终端测试服务器进行了修改并添加了额外的注释，以帮助促进学习并消除对POSIX shell的依赖。

相关 MCP