LangGraph 代理 + MCP

项目概述

LangChain-MCP-Adapters 是由 LangChain AI 提供的一个工具包，它使 AI 代理能够通过模型上下文协议 (MCP) 与外部工具和数据源进行交互。该项目提供了一个用户友好的界面，用于部署可以通过 MCP 工具访问各种数据源和 API 的 ReAct 代理。

特性

• Streamlit 界面: 一个用户友好的 Web 界面，用于与带有 MCP 工具的 LangGraph ReAct 代理 进行交互
• 工具管理: 通过 UI 添加、移除和配置 MCP 工具（支持 Smithery JSON 格式）。此操作动态完成，无需重启应用程序
• 流式响应: 实时查看代理响应和工具调用
• 对话历史: 跟踪并管理与代理的对话

MCP 架构

模型上下文协议 (MCP) 包含三个主要组件：

1. MCP 主机: 通过 MCP 访问数据的程序，例如 Claude Desktop、IDE 或 LangChain/LangGraph。

2. MCP 客户端: 与服务器保持 1:1 连接的协议客户端，充当主机与服务器之间的中介。

3. MCP 服务器: 一个轻量级程序，通过标准化的模型上下文协议暴露特定功能，作为主要的数据源。

使用 Docker 快速开始

您无需设置本地 Python 环境，即可使用 Docker 轻松运行该项目。

需求（Docker Desktop）

请从以下链接安装 Docker Desktop：

• 安装 Docker Desktop

使用 Docker Compose 运行

1. 导航到 dockers 目录

cd dockers

2. 在项目根目录中创建包含您的 API 密钥的 .env 文件。

cp .env.example .env

将您获取的 API 密钥输入到 .env 文件中。

（注意）并非所有 API 密钥都是必需的。只需输入您需要的密钥。

• ANTHROPIC_API_KEY: 如果您输入 Anthropic API 密钥，可以使用 "claude-3-7-sonnet-latest"、"claude-3-5-sonnet-latest"、"claude-3-haiku-latest" 模型。
• OPENAI_API_KEY: 如果您输入 OpenAI API 密钥，可以使用 "gpt-4o"、"gpt-4o-mini" 模型。
• LANGSMITH_API_KEY: 如果您输入 LangSmith API 密钥，可以使用 LangSmith 追踪功能。

ANTHROPIC_API_KEY=your_anthropic_api_key
OPENAI_API_KEY=your_openai_api_key
LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_PROJECT=LangGraph-MCP-Agents

当使用登录功能时，将 USE_LOGIN 设置为 true，并输入 USER_ID 和 USER_PASSWORD。

USE_LOGIN=true
USER_ID=admin
USER_PASSWORD=admin123

如果您不想使用登录功能，请将 USE_LOGIN 设置为 false。

USE_LOGIN=false

3. 选择与您的系统架构匹配的 Docker Compose 文件。

AMD64/x86_64 架构（Intel/AMD 处理器）

# 运行容器
docker compose -f docker-compose.yaml up -d

ARM64 架构（Apple Silicon M1/M2/M3/M4）

# 运行容器
docker compose -f docker-compose-mac.yaml up -d

4. 在浏览器中访问应用：http://localhost:8585

（注意）

• 如果您需要修改端口或其他设置，请在构建之前编辑 docker-compose.yaml 文件。

直接从源代码安装

1. 克隆本仓库

git clone https://github.com/teddynote-lab/langgraph-mcp-agents.git
cd langgraph-mcp-agents

2. 创建虚拟环境并使用 uv 安装依赖项

uv venv
uv pip install -r requirements.txt
source .venv/bin/activate  # 对于 Windows: .venv\Scripts\activate

3. 创建包含您的 API 密钥的 .env 文件（从 .env.example 复制）

cp .env.example .env

将您获取的 API 密钥输入到 .env 文件中。

（注意）并非所有 API 密钥都是必需的。只需输入您需要的密钥。

• ANTHROPIC_API_KEY: 如果您输入 Anthropic API 密钥，可以使用 "claude-3-7-sonnet-latest"、"claude-3-5-sonnet-latest"、"claude-3-haiku-latest" 模型。
• OPENAI_API_KEY: 如果您输入 OpenAI API 密钥，可以使用 "gpt-4o"、"gpt-4o-mini" 模型。
• LANGSMITH_API_KEY: 如果您输入 LangSmith API 密钥，可以使用 LangSmith 追踪功能。

ANTHROPIC_API_KEY=your_anthropic_api_key
OPENAI_API_KEY=your_openai_api_key
LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_PROJECT=LangGraph-MCP-Agents

4. （新增）使用登录/登出功能

当使用登录功能时，将 USE_LOGIN 设置为 true，并输入 USER_ID 和 USER_PASSWORD。

USE_LOGIN=true
USER_ID=admin
USER_PASSWORD=admin123

如果您不想使用登录功能，请将 USE_LOGIN 设置为 false。

USE_LOGIN=false

使用方法

1. 启动 Streamlit 应用程序。

streamlit run app.py

2. 应用程序将在浏览器中运行，并显示主界面。

3. 使用侧边栏添加和配置 MCP 工具

访问 Smithery 查找有用的 MCP 服务器。

首先，选择您想要使用的工具。

点击右侧 JSON 配置中的 COPY 按钮。

将复制的 JSON 字符串粘贴到 Tool JSON 部分。

点击 Add Tool 按钮将其添加到“已注册工具列表”部分。

最后，点击“Apply”按钮以应用更改，从而使用新工具初始化代理。

4. 检查代理的状态。

5. 通过聊天界面提问，与利用已配置 MCP 工具的 ReAct 代理进行交互。

动手教程

对于希望更深入学习 MCP 与 LangGraph 集成原理的开发者，我们提供了一份全面的 Jupyter Notebook 教程：

• 链接：MCP-HandsOn-KOR.ipynb

本动手教程涵盖以下内容：

1. MCP 客户端设置 - 学习如何配置和初始化 MultiServerMCPClient，以连接到 MCP 服务器
2. 本地 MCP 服务器集成 - 通过 SSE 和 Stdio 方法连接到本地运行的 MCP 服务器
3. RAG 集成 - 使用 MCP 的检索工具获取文档检索能力
4. 混合传输方式 - 在单个智能体中结合使用不同的传输协议（SSE 和 Stdio）
5. LangChain 工具 + MCP - 将原生 LangChain 工具与 MCP 工具集成在一起

本教程提供了实用的示例，并配有逐步解释，帮助您理解如何构建并将 MCP 工具集成到 LangGraph 智能体中。

许可证

MIT 许可证

参考资料

• https://github.com/langchain-ai/langchain-mcp-adapters

langgraph-mcp-agents 快速上手指南

langgraph-mcp-agents 是一个基于 Streamlit 的可视化工具，旨在帮助开发者轻松部署和管理集成了 MCP (Model Context Protocol) 工具的 LangGraph ReAct 智能体。通过该工具，你可以动态配置外部数据源和 API，无需重启应用即可让 AI 智能体调用各种 MCP 服务。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: Windows, macOS (Intel/Apple Silicon), 或 Linux
• Python 版本: ≥ 3.12
• 前置依赖 (二选一):
  • 方案 A (推荐): 安装 Docker Desktop (无需配置本地 Python 环境)
  • 方案 B: 安装 Python 3.12+ 及 uv 包管理工具 (用于源码安装)
• API Keys: 至少准备一个模型服务商的密钥 (Anthropic 或 OpenAI)

安装步骤

你可以选择使用 Docker 快速启动，或者从源码直接安装。

方案一：使用 Docker (推荐)

此方法最简单，避免了环境配置冲突。

1. 克隆项目并进入目录

   git clone https://github.com/teddylee777/langgraph-mcp-agents.git
   cd langgraph-mcp-agents/dockers
   

2. 配置环境变量 复制示例文件并编辑 .env，填入你的 API Key。

   cp ../.env.example .env
   

   编辑 .env 文件（只需填写你需要的密钥）：

   # Anthropic (支持 claude-3-7-sonnet-latest 等)
   ANTHROPIC_API_KEY=your_anthropic_api_key
   
   # OpenAI (支持 gpt-4o, gpt-4o-mini)
   OPENAI_API_KEY=your_openai_api_key
   
   # LangSmith (可选，用于追踪调试)
   LANGSMITH_API_KEY=your_langsmith_api_key
   LANGSMITH_TRACING=true
   LANGSMITH_ENDPOINT=https://api.smith.langchain.com
   LANGSMITH_PROJECT=LangGraph-MCP-Agents
   
   # 登录功能配置 (不需要可设为 false)
   USE_LOGIN=false
   

3. 启动容器 根据你的处理器架构选择对应的命令：

   • Intel/AMD 处理器 (AMD64/x86_64):

     docker compose -f docker-compose.yaml up -d
     

   • Apple Silicon M1/M2/M3/M4 (ARM64):

     docker compose -f docker-compose-mac.yaml up -d
     

4. 访问应用 打开浏览器访问：http://localhost:8585

---

方案二：源码安装 (本地开发)

适合需要修改代码或进行深度开发的用户。

1. 克隆项目

   git clone https://github.com/teddynote-lab/langgraph-mcp-agents.git
   cd langgraph-mcp-agents
   

2. 创建虚拟环境并安装依赖 推荐使用 uv 进行快速安装：

   uv venv
   uv pip install -r requirements.txt
   # Linux/macOS 激活环境
   source .venv/bin/activate
   # Windows 激活环境
   # .venv\Scripts\activate
   

3. 配置环境变量

   cp .env.example .env
   

   参照上述 Docker 方案中的步骤，编辑 .env 文件填入 API Key。

4. 启动应用

   streamlit run app.py
   

   应用将在默认浏览器中自动打开（通常为 http://localhost:8501）。

基本使用

启动应用后，按照以下步骤配置并使用 MCP 智能体：

1. 获取 MCP 工具配置

   • 访问 Smithery 查找你需要的 MCP 服务器（如文件系统、数据库、搜索引擎等）。
   • 找到目标工具后，点击右侧 JSON 配置区域的 COPY 按钮复制 JSON 字符串。

2. 添加工具到界面

   • 在应用左侧边栏找到 Tool JSON 输入框。
   • 粘贴刚才复制的 JSON 字符串。
   • 点击 Add Tool 按钮，该工具将出现在 "Registered Tools List" 列表中。

3. 应用配置

   • 配置完成后，点击侧栏底部的 Apply 按钮。
   • 系统将重新初始化智能体，加载新添加的工具（无需重启服务）。

4. 开始对话

   • 在主聊天界面输入问题。
   • 智能体将根据你的指令，自动调用已配置的 MCP 工具执行任务（如读取文件、查询数据等），并实时流式返回结果和工具调用过程。

提示: 如需深入了解 MCP 与 LangGraph 的集成原理，可参考项目根目录下的 MCP-HandsOn-KOR.ipynb 教程笔记。