LangGraph × FastMCP 2.0 集成示例 🚀

强强联合：轻松构建企业级AI工作流，效率翻倍！

本项目展示了 LangGraph 与 FastMCP 2.0 的两种典型集成方式：

1. 客户端集成：将 FastMCP 服务器暴露的工具作为 LangGraph 工作流中的可调用节点
2. 服务端封装：把 LangGraph Agent 封装为 FastMCP 服务器，对外以标准协议提供能力

📋 目录

• 快速开始
• 项目结构
• 安装依赖
• 配置环境
• 运行示例
  • 示例1: MCP服务器
  • 示例2: LangGraph作为MCP客户端
  • 示例3: LangGraph封装为MCP服务器
• 使用MCP Inspector
• 架构说明
• 常见问题

🚀 快速开始

1. 克隆项目

git clone <repository-url>
cd fastmcp_demo

2. 安装依赖

使用 pip:

pip install -r requirements.txt

使用 uv (推荐):

uv pip install -r requirements.txt

使用 poetry:

poetry install

3. 配置环境变量

创建 .env 文件并配置你的 API 密钥：

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，添加你的 API 密钥
# DEEPSEEK_API_KEY=sk-your-deepseek-api-key-here

4. 运行示例

# 启动 MCP 服务器
python mcp_server_sample.py

# 在新终端运行 LangGraph 客户端
python langgraph_use_mcp_as_client.py

# 或运行 LangGraph 服务器
python langgraph_use_mcp_as_server.py

📁 项目结构

fastmcp_demo/
├── mcp_server_sample.py           # MCP 服务器示例（提供数学工具）
├── langgraph_use_mcp_as_client.py # LangGraph 调用 MCP 服务
├── langgraph_use_mcp_as_server.py # LangGraph 封装为 MCP 服务器
├── requirements.txt                # Python 依赖
├── pyproject.toml                 # 项目配置
├── .env.example                   # 环境变量模板
└── README.md                      # 本文档

📦 安装依赖

核心依赖

• FastMCP >= 2.12.0 - MCP 服务器框架
• LangGraph >= 0.2.0 - 工作流编排框架
• LangChain >= 0.3.0 - LLM 应用框架
• langchain-mcp-adapters >= 0.1.0 - MCP 适配器

安装方法

方法 1: 使用 pip

pip install -r requirements.txt

方法 2: 使用 uv (推荐，更快)

# 安装 uv
pip install uv

# 使用 uv 安装依赖
uv pip install -r requirements.txt

方法 3: 使用 poetry

# 安装 poetry
pip install poetry

# 安装依赖
poetry install

🔧 配置环境

1. 创建 .env 文件

# DeepSeek API配置
DEEPSEEK_API_KEY=sk-your-deepseek-api-key-here

# OpenAI API配置 (可选)
# OPENAI_API_KEY=sk-your-openai-api-key-here

2. 获取 API 密钥

• DeepSeek: 访问 DeepSeek 官网 注册获取 API 密钥
• OpenAI (可选): 访问 OpenAI Platform 获取

🎯 运行示例

示例1: MCP服务器

启动一个提供数学计算工具的 MCP 服务器：

python mcp_server_sample.py

服务器将在 http://127.0.0.1:8000/mcp 启动，提供以下工具：

• add(a, b) - 加法
• multiply(a, b) - 乘法
• subtract(a, b) - 减法
• divide(a, b) - 除法

示例2: LangGraph作为MCP客户端

在另一个终端窗口运行：

# 确保 MCP 服务器已经在运行
python langgraph_use_mcp_as_client.py

这个示例将：

1. 连接到 MCP 服务器
2. 获取可用工具
3. 构建 LangGraph 工作流
4. 使用工具解决数学问题

示例输出：

=== 获取MCP工具 ===
可用工具: ['add', 'multiply', 'subtract', 'divide']

=== 测试数学计算 ===
测试问题: what's (3 + 5) x 12?
最终答案: The result of (3 + 5) × 12 is 96.

示例3: LangGraph封装为MCP服务器

运行 LangGraph 封装的 MCP 服务器：

python langgraph_use_mcp_as_server.py

服务器将在 http://127.0.0.1:8004/mcp 启动，提供以下工具：

• process_text_with_langgraph - 使用 LangGraph 处理文本
• analyze_sentiment - 情感分析
• summarize_text - 文本摘要

测试服务器功能

# 运行内置测试
python langgraph_use_mcp_as_server.py --test

🔍 使用MCP Inspector

MCP Inspector 是一个可视化工具，用于测试和调试 MCP 服务器。

安装 Inspector

# 使用 npm 安装
npm install -g @modelcontextprotocol/inspector

# 或使用 npx 直接运行（无需安装）
npx @modelcontextprotocol/inspector

使用 Inspector

1. 启动你的 MCP 服务器
2. 运行 Inspector：

   npx @modelcontextprotocol/inspector

3. 在浏览器中打开 http://localhost:6274
4. 连接到你的 MCP 服务器 URL（如 http://127.0.0.1:8000/mcp）
5. 测试工具调用

🏗️ 架构说明

客户端集成模式

┌─────────────┐     HTTP/WS      ┌──────────────┐
│  LangGraph  │ ───────────────> │ MCP Server   │
│   Client    │                   │   (Tools)    │
└─────────────┘                   └──────────────┘
      │                                   │
      v                                   v
┌─────────────┐                   ┌──────────────┐
│    LLM      │                   │   Execute    │
│  (DeepSeek) │                   │   Function   │
└─────────────┘                   └──────────────┘

服务端封装模式

┌─────────────┐     HTTP/WS      ┌──────────────┐
│ MCP Client  │ ───────────────> │ FastMCP      │
│             │                   │   Server     │
└─────────────┘                   └──────────────┘
                                         │
                                         v
                                  ┌──────────────┐
                                  │  LangGraph   │
                                  │   Workflow   │
                                  └──────────────┘
                                         │
                                         v
                                  ┌──────────────┐
                                  │     LLM      │
                                  │  (DeepSeek)  │
                                  └──────────────┘

📝 扩展开发

添加新工具

在 mcp_server_sample.py 中添加：

@mcp.tool()
def your_tool(param1: str, param2: int) -> str:
    """Your tool description"""
    # 实现你的工具逻辑
    return result

创建新的 LangGraph 工作流

from langgraph.graph import StateGraph, START, END

def create_custom_workflow():
    workflow = StateGraph(YourStateType)
    
    # 添加节点
    workflow.add_node("node1", node1_function)
    workflow.add_node("node2", node2_function)
    
    # 添加边
    workflow.add_edge(START, "node1")
    workflow.add_edge("node1", "node2")
    workflow.add_edge("node2", END)
    
    return workflow.compile()

❓ 常见问题

1. 连接 MCP 服务器失败

问题: 连接失败: Connection refused

解决方案:

• 确保 MCP 服务器已经启动
• 检查端口是否被占用：lsof -i :8000
• 更换端口号

2. API 密钥错误

问题: Invalid API key

解决方案:

• 检查 .env 文件中的 API 密钥是否正确
• 确保已经加载环境变量：load_dotenv()

3. 依赖安装失败

问题: No matching distribution found

解决方案:

• 升级 pip：pip install --upgrade pip
• 使用国内镜像：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

4. 工具调用超时

问题: Tool execution timeout

解决方案:

• 在 MCP Inspector 中调整超时时间
• 优化工具实现，减少处理时间
• 考虑异步处理

🤝 贡献指南

欢迎提交 Pull Request 或创建 Issue！

开发流程

1. Fork 项目
2. 创建特性分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m 'Add your feature'
4. 推送分支：git push origin feature/your-feature
5. 创建 Pull Request

📄 许可证

MIT License

🔗 相关链接

• FastMCP 文档
• LangGraph 文档
• MCP 协议规范
• DeepSeek API 文档

💡 提示

• 使用 uv 可以显著提升依赖安装速度
• 开发时可以使用 --test 参数快速测试功能
• MCP Inspector 是调试 MCP 服务器的最佳工具
• 建议在虚拟环境中运行项目

---