内容
# 第五只大象MCP服务器：DIY指南
本指南提供了一步一步的完整教程，教你如何从零开始创建和运行一个简单的模型上下文协议（MCP）服务器。
## 目录
1. [先决条件](#先决条件)
- [安装pyenv](#1-安装pyenv如果尚未安装)
- [安装Python 3.11](#2-安装python-311)
- [安装uv](#3-安装uv)
2. [步骤1：项目设置](#步骤1项目设置)
3. [步骤2：使用uv初始化Python项目](#步骤2使用uv初始化python项目)
4. [步骤3：创建和激活虚拟环境](#步骤3创建和激活虚拟环境)
5. [步骤4：同步依赖（非必需）](#步骤4同步依赖)
6. [步骤5：添加MCP依赖](#步骤5添加mcp依赖)
7. [步骤6：验证安装](#步骤6验证安装)
8. [步骤7：编辑服务器代码](#步骤7编辑服务器代码)
9. [步骤8：使用MCP检查器进行本地调试](#步骤8使用mcp检查器进行本地调试)
10. [步骤9：配置Claude Desktop](#步骤9配置claude-desktop)
11. [故障排除](#故障排除)
## 先决条件
开始之前，请确保您已安装以下内容：
### 1. 安装pyenv（如果尚未安装）
pyenv允许您轻松管理多个Python版本。
**macOS：**
```sh
brew install pyenv
```
**Linux：**
```sh
curl https://pyenv.run | bash
```
**Windows：**
```powershell
# 使用PowerShell安装pyenv-win
Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
```
将pyenv添加到您的shell配置文件中：
**macOS/Linux（zsh）：**
```sh
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc
```
**Windows：**
```powershell
# 重启PowerShell或命令提示符后，pyenv-win将自动添加到您的PATH中
```
### 2. 安装Python 3.11
安装并设置Python 3.11为您的本地版本：
```sh
pyenv install 3.11.9
pyenv local 3.11.9
```
验证Python版本：
```sh
python --version
# 输出：Python 3.11.9
```
### 3. 安装uv
安装[uv](https://github.com/astral-sh/uv)以实现快速的Python包管理：
**macOS/Linux：**
```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**Windows：**
```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
验证uv安装：
```sh
uv --version
```
## 步骤1：项目设置
首先，为您的项目创建一个目录并进入其中。
```sh
mkdir fifth-elephant-mcp
cd fifth-elephant-mcp
```
## 步骤2：使用`uv`初始化Python项目
使用`uv`初始化一个新的Python项目。这将创建一个虚拟环境和一个`pyproject.toml`文件。
```sh
uv init --quiet
```
## 步骤3：创建和激活虚拟环境
使用Python 3.11创建虚拟环境：
```sh
uv venv --python 3.11.9
```
激活虚拟环境：
**macOS/Linux：**
```sh
source .venv/bin/activate
```
**Windows（命令提示符）：**
```cmd
.venv\Scripts\activate.bat
```
验证您是否在虚拟环境中（您应该在终端提示符中看到`(.venv)`）：
## 步骤4：同步依赖（非必需）
同步项目依赖以确保一切正常：
```sh
uv sync
```
## 步骤5：添加MCP依赖
将`mcp`库与CLI额外功能添加到您的项目依赖中。
```sh
uv add "mcp[cli]"
```
**注意：** 安装MCP CLI时，它可能会要求您安装其他依赖。按`y`确认。
## 步骤6：验证安装
验证所有组件是否正确安装：
```sh
# 验证Python版本
python --version
# 输出：Python 3.11.9
# 验证uv版本
uv --version
# 验证MCP库已安装（应为1.11或更高版本）
python -c "from mcp.server.fastmcp import __version__; print(__version__)"
```
## 步骤7：编辑服务器代码
当您运行`uv init`时，已经创建了一个`main.py`文件。编辑此文件并用以下代码替换其内容。此代码设置了一个具有两个工具的`FastMCP`服务器：`hello_world`和`add`。
```python
from mcp.server.fastmcp import FastMCP
# 创建一个MCP服务器
mcp = FastMCP("Fifth Elephant")
# 添加一个hello world工具
@mcp.tool()
def hello_world() -> str:
"""返回友好的问候语。"""
return "hello world"
# 添加一个加法工具
@mcp.tool()
def add(a: int, b: int) -> int:
"""将两个数字相加。"""
return a + b
if __name__ == "__main__":
mcp.run()
```
## 步骤8：使用MCP检查器进行本地调试
在开发和测试过程中，您可以使用MCP检查器。
运行以下命令 -
```
uv run mcp dev main.py
```
这将启动检查器。它将在您的浏览器中打开。在左侧边栏中点击连接。
## 步骤9：配置Claude Desktop
如果您尚未安装Claude Desktop，请安装它以使用您的MCP服务器：
1. 从[claude.ai](https://claude.ai/download)下载Claude Desktop
2. 安装并设置Claude Desktop
要将您的MCP服务器与Claude Desktop一起使用，您需要使用绝对路径配置它。
### 获取绝对路径
首先，获取虚拟环境的Python和`main.py`文件的绝对路径：
```sh
# 获取虚拟环境的Python的绝对路径
which python
# 获取main.py文件的绝对路径
pwd
```
**Windows（命令提示符）：**
```cmd
# 获取虚拟环境的Python的绝对路径
where python
# 获取main.py文件的绝对路径
cd
```
### 配置Claude Desktop
1. 打开Claude Desktop
2. 进入设置 → 开发者 → 编辑配置
3. 将您的MCP服务器配置添加到`config.json`文件中：
**macOS/Linux：**
```json
{
"mcpServers": {
"fifth-elephant": {
"command": "/绝对/路径/到/您的/.venv/bin/python",
"args": ["/绝对/路径/到/您的/main.py"]
}
}
}
```
**Windows：**
```json
{
"mcpServers": {
"fifth-elephant": {
"command": "C:\\绝对\\路径\\到\\您的\\.venv\\Scripts\\python.exe",
"args": ["C:\\绝对\\路径\\到\\您的\\main.py"]
}
}
}
```
**重要：**
- **macOS/Linux：** 用`which python`和`pwd`命令获得的实际绝对路径替换`/绝对/路径/到/您的/.venv/bin/python`和`/绝对/路径/到/您的/main.py`。
- **Windows：** 用`where python`和`cd`/`Get-Location`命令获得的实际绝对路径替换`C:\\绝对\\路径\\到\\您的\\.venv\\Scripts\\python.exe`和`C:\\绝对\\路径\\到\\您的\\main.py`。注意Windows路径中的双反斜杠（`\\`）。
**配置文件位置：**
- **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux：** `~/.config/claude/claude_desktop_config.json`
## 故障排除
如果您遇到问题，请尝试这些常见的解决方案：
### 1. 虚拟环境问题
确保您的虚拟环境已激活：
**macOS/Linux：**
```sh
# 激活虚拟环境
source .venv/bin/activate
# 验证您是否在虚拟环境中
which python
# 输出：/路径/到/您的/项目/.venv/bin/python
```
**Windows（命令提示符）：**
```cmd
# 激活虚拟环境
.venv\Scripts\activate.bat
# 验证您是否在虚拟环境中
where python
# 输出：C:\路径\到\您的\项目\.venv\Scripts\python.exe
```
### 2. 依赖问题
同步您的依赖：
```sh
uv sync
```
### 3. MCP检查器配置
如果您在使用MCP检查器时遇到问题，请使用以下设置：
- **命令：** `uv`
- **参数：** `run --with mcp mcp run main.py`
**注意：** 命令应为`uv`，而不是`mcp-server-everything`或类似变体。
### 4. 路径问题
确保在Claude Desktop配置中使用绝对路径。使用：
**macOS/Linux：**
```sh
# 获取虚拟环境中Python的绝对路径
which python
# 获取项目目录的绝对路径
pwd
```
**Windows（命令提示符）：**
```cmd
# 获取虚拟环境中Python的绝对路径
where python
# 获取项目目录的绝对路径
cd
```
然后用完整的绝对路径更新您的`config.json`。记得在JSON中使用Windows路径的双反斜杠（`\\`）。
