mcp-server-example

🚀 MCP 服务器示例实现

本仓库提供了一个用于教育目的的 Model Context Protocol (MCP) 服务器实现。该代码展示了如何构建一个功能性的 MCP 服务器，使其能够与各类 LLM 客户端集成。

要查看完整的教程，请参考 YouTube 视频教程。

🚀 快速开始

安装 uv 包管理器

在 MacOS/Linux 上，可使用以下命令安装 uv 包管理器：

curl -LsSf https://astral.sh/uv/install.sh | sh

请确保之后重启终端，以便 uv 命令生效。

项目设置

1. 创建并初始化项目：

# 创建新目录用于我们的项目
uv init mcp-server
cd mcp-server

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate  # 在 Windows 上使用：.venv\Scripts\activate

2. 安装依赖项：

uv add "mcp[cli]" httpx

3. 创建服务器实现文件：

touch main.py

运行服务器

1. 启动 MCP 服务器：

uv run main.py

2. 服务器启动并准备好接受连接

连接到 Claude Desktop

1. 从官方网站安装 Claude Desktop。
2. 配置 Claude Desktop 使用您的 MCP 服务器： 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
    "mcpServers": {
        "mcp-server": {
            "command": "uv",  # 建议使用 uv 命令的绝对路径
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/YOUR/mcp-server",
                "run",
                "main.py"
            ]
        }
    }
}

3. 重启 Claude Desktop

✨ 主要特性

• 拥有不断增长的预构建集成列表，LLM 可直接插入使用。
• 具备灵活性，能轻松在不同 LLM 提供商和供应商之间切换。
• 遵循保护数据的最佳实践，在您的基础架构内运行。

📦 安装指南

系统要求

• Python 3.10 或更高版本
• MCP SDK 1.2.0 或更高版本
• uv 包管理器

安装步骤

安装 uv 包管理器

在 MacOS/Linux 上：

curl -LsSf https://astral.sh/uv/install.sh | sh

请确保之后重启终端，以便 uv 命令生效。

项目设置

1. 创建并初始化项目：

# 创建新目录用于我们的项目
uv init mcp-server
cd mcp-server

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate  # 在 Windows 上使用：.venv\Scripts\activate

2. 安装依赖项：

uv add "mcp[cli]" httpx

3. 创建服务器实现文件：

touch main.py

📚 详细文档

什么是 MCP？

MCP（模型上下文协议）是一项开放协议，它标准化了应用程序为 LLM 提供上下文的方式。可以将 MCP 想象成 USB - C 端口，它为 AI 应用程序提供了一种标准方式来连接到不同的数据源和工具。

架构概述

MCP 采用客户端 - 服务器架构，其中主机应用程序可以连接到多个服务器：

• MCP 主机：如 Claude Desktop、IDE 或 AI 工具等，希望访问 MCP 数据的应用程序。
• MCP 客户端：与服务器保持一对一连接的协议客户端。
• MCP 服务器：通过标准化模型上下文协议暴露特定功能的轻量级程序。
• 数据源：本地（文件、数据库）和远程服务（API）等，MCP 服务器可以访问。

MCP 核心概念

MCP 服务器可以提供三种主要类型的功效：

• 资源：文件样态的数据，可供客户端读取（如 API 响应或文件内容）。
• 工具：可供 LLM 调用的函数（需用户批准）。
• 提示词：预写模板，帮助用户完成特定任务。

🔧 技术细节

系统要求

• Python 3.10 或更高版本
• MCP SDK 1.2.0 或更高版本
• uv 包管理器

快速入门流程

安装 uv 包管理器

在 MacOS/Linux 上，通过 curl -LsSf https://astral.sh/uv/install.sh | sh 命令安装 uv 包管理器，安装后需重启终端使 uv 命令生效。

项目设置

创建并初始化项目，创建虚拟环境并激活，安装依赖项，创建服务器实现文件。

运行服务器

使用 uv run main.py 命令启动 MCP 服务器。

连接到 Claude Desktop

安装 Claude Desktop 后，编辑 ~/Library/Application Support/Claude/claude_desktop_config.json 配置文件，配置完成后重启 Claude Desktop。

📄 许可证

此项目根据 MIT 许可证发布。更多细节请查阅 LICENSE 文件。

💡 使用建议

若服务器未被 Claude Desktop 检测到，可按以下步骤排查：

1. 检查配置文件路径和权限。
2. 确保配置中的绝对路径正确。
3. 确保 uv 已正确安装且可访问。
4. 查看 Claude Desktop 日志获取错误信息。