使用 Python 构建基础 MCP 服务器

如果你曾经希望过能让 Claude 这样的 AI 模型直接访问你电脑上的文件或执行自定义代码——现在好消息来了！Model Context Protocol（MCP）正是为此而设计的协议。本文将带你一步步构建一个简单易用的 MCP 服务器模板。你无需精通 AI 或服务器开发，我们将循序渐进地介绍每个部分的要点。

---

本文将带你实现

• 利用 Python 和 MCP SDK 构建一个小型服务器

• 开发两个工具函数，分别用于读取 CSV 文件和 Parquet 文件（这两种格式分别适用于电子表格数据和数据工程/分析场景）

• 构建一个清晰的项目目录结构，方便后续扩展更多工具或功能

• 实现与 Claude for Desktop 的连接，让你用自然语言轻松询问：“这个 CSV 文件有多少行多少列？”等问题

---

为什么选择这篇教程？

• 接入 Claude： 如果你了解 Claude 并希望将其与你的工具或数据结合，这篇文章能够帮助你实现基础连接。

• 探索 MCP： 想深入了解 MCP 工作原理的开发者，本教程提供了简明易懂的实践示例。

• 稳固起点： 这是一个良好的开端，后续你可以以此模板为基础，开发更先进的工具服务器。

本教程不依赖任何 web 框架或复杂部署，一切代码均在本地环境中运行，主要依赖 Python 及常用库（如 pandas）。

---

什么是 MCP？为什么它值得关注？

MCP，全称 Model Context Protocol，旨在允许像 Claude for Desktop 这样的应用安全地与外部数据和你定义的自定义工具互动。你可以把它理解成你自己的 mini API，只不过这个接口并不是向全网开放，而是专门供本地 AI 助手调用。

通过 MCP，你可以轻松实现：

• 让 Claude 读取本地文件或查询数据库

• 编写小巧实用的工具函数（例如对数据集进行摘要统计）

• 构建用于指导 Claude 执行任务的可重用提示语

本文的重点在于工具部分——通过编写简单的 Python 函数，让 AI 模型调用并获得实际数据反馈。

---

我们要构建什么？

最终成果预览

• 一个名为 mix_server 的本地 MCP 服务器

• 两个工具：summarize_csv_file 和 summarize_parquet_file，分别用于对 CSV 与 Parquet 数据进行摘要统计

• 模块化、清晰的文件夹结构，方便后续扩展更多工具

• 与 Claude for Desktop 的成功连接，支持通过自然语言调用上述工具

接下来，我们从项目的基本搭建开始。

---

项目设置（分步指南）

本教程推荐使用 uv ——一个快速、现代化的 Python 项目管理工具。它集成了依赖管理、虚拟环境配置及脚本运行功能，让项目设置更为简洁高效。

第一步：安装 uv

在终端中运行以下命令安装 uv：

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

安装完成后，重启终端以确保 uv 命令可用。接着，可通过下面命令验证安装成功：

uv --version

第二步：创建项目目录

在终端执行以下命令来初始化项目文件夹：

uv init mix_server
cd mix_server

这一步会生成一个包含 pyproject.toml 的基础项目，以便管理依赖。

第三步：创建虚拟环境

为了将项目依赖隔离出来，我们需要创建并激活虚拟环境：

uv venv
source .venv/bin/activate

第四步：添加必需依赖

我们需要安装以下三个关键库：

• mcp[cli]：MCP SDK 及其命令行工具

• pandas：处理 CSV 及数据分析

• pyarrow：通过 Pandas 添加 Parquet 文件支持

使用 uv 添加依赖：

uv add "mcp[cli]" pandas pyarrow

第五步：构建清晰的文件夹结构

建议按照以下结构构建项目目录：

mix_server/
│
├── data/                 # 存放 CSV 与 Parquet 数据文件
│
├── tools/                # 存放 MCP 工具定义
│
├── utils/                # 存放可复用的数据读取逻辑
│
├── server.py             # MCP 服务器主入口
└── README.md             # 项目说明文档

在项目根目录创建文件夹和主要文件：

mkdir data tools utils
touch server.py

---

创建示例数据文件

为了给工具函数提供操作对象，我们需要两个数据文件：

• CSV 文件：适用于表格数据的简单文本格式

• Parquet 文件：一种高效的二进制列式存储格式，在数据处理与分析领域被广泛使用

创建 CSV 文件

在 data/ 文件夹下创建一个名为 sample.csv 的文件，并填入如下内容：

id,name,email,signup_date
1,Alice Johnson,[email protected],2023-01-15
2,Bob Smith,[email protected],2023-02-22
3,Carol Lee,[email protected],2023-03-10
4,David Wu,[email protected],2023-04-18
5,Eva Brown,[email protected],2023-05-30

这份文件提供了 5 条记录，共 4 个字段，适合作为数据摘要工具的示例数据。

将 CSV 转换为 Parquet

接下来，我们利用 Python 脚本将 CSV 数据转换为 Parquet 格式。创建一个名为 generate_parquet.py 的文件，内容如下：

# generate_parquet.py

import pandas as pd

# 读取 CSV 文件
df = pd.read_csv("data/sample.csv")

# 保存为 Parquet 文件（不保存行索引）
df.to_parquet("data/sample.parquet", index=False)

运行脚本生成文件：

uv run generate_parquet.py

运行后，data/ 文件夹中应包含两个文件：

data/
├── sample.csv
└── sample.parquet

【小贴士】

• CSV：简单易读，适用于较小数据集及快速预览

• Parquet：二进制列式存储，适合处理大数据和高效查询分析

---

编写数据文件读取的实用函数

为了避免重复代码，我们将数据读取逻辑放在 utils/ 文件夹下，创建一个模块文件 utils/file_reader.py，内容如下：

# utils/file_reader.py

import pandas as pd
from pathlib import Path

# 数据文件目录的基础路径
DATA_DIR = Path(__file__).resolve().parent.parent / "data"

def read_csv_summary(filename: str) -> str:
    """
    读取 CSV 文件并返回简单摘要。

    参数:
        filename: CSV 文件名（例如 'sample.csv'）

    返回:
        一个描述文件行数与列数的字符串摘要。
    """
    file_path = DATA_DIR / filename
    df = pd.read_csv(file_path)
    return f"CSV 文件 '{filename}' 包含 {len(df)} 行，{len(df.columns)} 列。"

def read_parquet_summary(filename: str) -> str:
    """
    读取 Parquet 文件并返回简单摘要。

    参数:
        filename: Parquet 文件名（例如 'sample.parquet'）

    返回:
        一个描述文件行数与列数的字符串摘要。
    """
    file_path = DATA_DIR / filename
    df = pd.read_parquet(file_path)
    return f"Parquet 文件 '{filename}' 包含 {len(df)} 行，{len(df.columns)} 列。"

这样，两种数据文件的读取逻辑就统一封装在一个模块中，方便后续在工具中调用。

---

将数据读取功能封装为 MCP 工具

现在，我们要把上面编写的读取逻辑封装成 MCP 工具，让 AI 助手可通过调用工具来获取文件摘要。

什么是 MCP 工具？

MCP 工具是一种经过装饰器标记的 Python 函数，注册到 MCP 服务器上后，可以被 AI 模型调用执行。通过 @mcp.tool() 装饰器，你可以将任何自定义函数暴露为一个供 AI 调用的接口。

为了保持代码整洁，我们首先在 server.py 中集中创建 MCP 服务器实例，然后在各个工具文件中导入并使用这个实例。

步骤 1：定义 MCP 服务器实例

在项目根目录下的 server.py 文件中添加如下代码：

# server.py

from mcp.server.fastmcp import FastMCP

# 创建全局 MCP 服务器实例，服务器名称为 "mix_server"
mcp = FastMCP("mix_server")

# 导入工具模块（装饰器注册工具）
import tools.csv_tools
import tools.parquet_tools

# 启动服务器
if __name__ == "__main__":
    mcp.run()

步骤 2：创建 CSV 文件摘要工具

在 tools/ 目录下创建文件 csv_tools.py，内容如下：

# tools/csv_tools.py

from server import mcp
from mcp.server.fastmcp import tool
from utils.file_reader import read_csv_summary

@mcp.tool()
def summarize_csv_file(filename: str) -> str:
    """
    对 CSV 文件进行摘要统计，返回文件行列数量。

    参数:
        filename: /data 目录下 CSV 文件名（如 'sample.csv'）

    返回:
        描述文件维度的字符串摘要。
    """
    return read_csv_summary(filename)

步骤 3：创建 Parquet 文件摘要工具

在 tools/ 目录下创建文件 parquet_tools.py，内容如下：

# tools/parquet_tools.py

from server import mcp
from mcp.server.fastmcp import tool
from utils.file_reader import read_parquet_summary

@mcp.tool()
def summarize_parquet_file(filename: str) -> str:
    """
    对 Parquet 文件进行摘要统计，返回文件行列数量。

    参数:
        filename: /data 目录下 Parquet 文件名（如 'sample.parquet'）

    返回:
        描述文件维度的字符串摘要。
    """
    return read_parquet_summary(filename)

由于工具是通过装饰器在导入时自动注册，只需确保 server.py 中导入了这两个模块，工具即可生效。

---

运行与测试你的 MCP 服务器

到目前为止，你已经完成了 MCP 服务器的全部代码工作，现在就让它跑起来，并通过 Claude for Desktop 来使用这些工具吧！

步骤 1：启动服务器

在项目根目录下，执行以下命令启动 MCP 服务器：

uv run server.py

启动后，终端不会显示过多输出，这是正常现象，表示服务器已在等待来自客户端（如 Claude）的连接。

步骤 2：安装 Claude for Desktop

如果你还未安装 Claude for Desktop，请前往 Anthropic 官网 下载适用于你操作系统的版本。请注意，目前 Linux 版本暂未支持。

步骤 3：配置 Claude 使用你的 MCP 服务器

Claude 需要知道如何连接到你的 MCP 服务器，这需要修改配置文件。

• Mac/Linux：打开或创建配置文件：

  code ~/Library/Application\ Support/Claude/claude_desktop_config.json
  

• Windows：配置文件路径为：

  %APPDATA%\Claude\claude_desktop_config.json
  

在该配置文件中添加如下 JSON 配置（注意替换 /ABSOLUTE/PATH/TO/mix_server 为你的项目绝对路径）：

{
  "mcpServers": {
    "mix_server": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/mix_server",
        "run",
        "server.py"
      ]
    }
  }
}

步骤 4：重启 Claude

修改配置文件后，重启 Claude for Desktop，你会在界面上看到新出现的工具图标（通常为锤子图标）。点击后，你将看到两个注册好的工具：

• summarize_csv_file

• summarize_parquet_file

步骤 5：尝试调用工具

你可以试着对 Claude 说：

• “请总结 sample.csv 文件的内容。”

• “sample.parquet 文件有多少行？”

Claude 会自动选择合适的工具，通过你的 MCP 服务器调用后返回结果。

常见问题排查

如果你的服务器或工具没有正常运行，请检查：

• 是否已正确执行 uv run server.py，且服务器未异常退出

• 配置文件中的路径是否准确

• data 文件夹中是否包含 sample.csv 和 sample.parquet

• Claude 界面上是否有加载错误提示

---

总结与后续拓展

恭喜！你已经搭建了一个完整可用的 MCP 服务器，具备以下能力：

• 使用 Python 与 MCP SDK 构建服务端

• 通过 pandas 从 CSV 与 Parquet 文件中读取真实数据并生成摘要

• 提供两个供 Claude 调用的工具：summarize_csv_file 与 summarize_parquet_file

• 采用了模块化的项目结构，便于后续功能扩展

• 成功通过简单配置，实现与 Claude for Desktop 的对接

同时你也学到了：

• 如何利用 uv 管理 Python 项目和虚拟环境

• 依赖管理以及如何用 pyproject.toml 维护项目环境

• 使用 @mcp.tool() 装饰器注册 MCP 工具

• 通过简单配置文件整合本地工具与 AI 助手

后续进阶建议

• 扩展更多工具功能
  例如，添加筛选数据、列出数据字段名称或统计数据指标（均值、中位数等）的工具。

• 使用资源接口
  利用 @mcp.resource() 暴露静态或动态数据，让 Claude 在决策前能获取更多上下文信息。

• 深入探索交互提示
  创建可重用的提示模版（@mcp.prompt()），从而指导 AI 在调用工具时的交互行为。

• 考虑异步逻辑
  当你需要从 API 或数据库中拉取数据时，可以将工具函数改写为异步函数 async def，以充分利用 FastMCP 的支持。

• 开发自定义客户端
  如果不使用 Claude，也可以基于 MCP SDK 的 ClientSession 接口开发你自己的客户端应用。

你现在有一个模板，可以在未来的项目中重复使用。如果你将其发布在 GitHub 上，其他人可以对其进行分叉、扩展并从中学习。 这不仅仅是一个演示——它是一个工具链的基础，在这个工具链中，你可以定义自己的人工智能驱动的工作流，并以一种可控的、模块化的方式将其暴露给大语言模型。