langchain-ai/langsmith-mcp-server
GitHub: langchain-ai/langsmith-mcp-server
一个将 LangSmith 可观测性平台与 MCP 客户端无缝集成的服务器，使语言模型能够直接查询对话历史、Prompts、Traces、数据集及账单等数据。
Stars: 127 | Forks: 39
# 🦜🛠️ LangSmith MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/release/python-3100/)
一个生产就绪的 [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server，提供与 [LangSmith](https://smith.langchain.com) 可观测性平台的无缝集成。该 server 使语言模型能够从 LangSmith 获取对话历史、prompts、runs 和 traces、数据集、实验以及账单使用情况。
## 📋 示例用例
该 server 提供了强大的功能，包括：
- 💬 **对话历史**：“从项目 'my-chatbot' 的线程 'thread-123' 中获取我的对话历史”（按字符预算进行分页）
- 📚 **Prompt 管理**：“获取我工作区中的所有公开 prompts” / “拉取 'legal-case-summarizer' prompt 的模板”
- 🔍 **Traces 与 Runs**：“获取项目 'alpha' 中最近的 10 次根 runs” / “获取 trace <uuid> 的所有 runs（第 2 页，共 5 页）”
- 📊 **数据集**：“列出 chat 类型的数据集” / “读取数据集 'customer-support-qa' 中的示例”
- 🧪 **实验**：“列出数据集 'my-eval-set' 的实验及其延迟和成本指标”
- 📈 **账单**：“获取 2025 年 9 月的账单使用情况”
## 🚀 快速开始
LangSmith MCP Server 的**托管版本**支持通过 HTTP-streamable 传输使用，因此您无需自行运行 server 即可连接：
- **URL:** `https://langsmith-mcp-server.onrender.com/mcp`
- **托管：** [Render](https://render.com)，使用该项目的 Dockerfile 从此公共仓库构建。
像使用任何 HTTP-streamable MCP server 一样使用它：将您的客户端指向该 URL，并在 `LANGSMITH-API-KEY` header 中发送您的 LangSmith API 密钥。无需本地安装或 Docker。
**示例（Cursor `mcp.json`）：**
```
{
"mcpServers": {
"LangSmith MCP (Hosted)": {
"url": "https://langsmith-mcp-server.onrender.com/mcp",
"headers": {
"LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here"
}
}
}
}
```
可选 headers：`LANGSMITH-WORKSPACE-ID`、`LANGSMITH-ENDPOINT`（与下方 [Docker 部署](#-docker-deployment-http-streamable)章节中的相同）。
## 🛠️ 可用工具
LangSmith MCP Server 提供以下工具用于与 LangSmith 集成。
### 📚 Prompt 管理
| 工具名称 | 描述 |
|-----------|-------------|
| `list_prompts` | 从 LangSmith 获取 prompts，支持按可见性（公开/私有）和限制进行可选过滤。 |
| `get_prompt_by_name` | 通过确切名称获取特定 prompt，返回 prompt 详情和模板。 |
| `push_prompt` | 仅作文档说明：如何创建并将 prompts 推送到 LangSmith。 |
### 🔍 Traces 与 Runs
| 工具名称 | 描述 |
|-----------|-------------|
| `fetch_runs` | 从一个或多个项目中获取 LangSmith runs（traces、tools、chains 等）。支持过滤器（run_type、error、is_root）、FQL（`filter`、`trace_filter`、`tree_filter`）和排序。设置 `trace_id` 时，返回**基于字符分页**的页面；否则返回最多达 `limit` 的一批数据。请始终传递 `limit` 和 `page_number`。 |
| `list_projects` | 列出 LangSmith 项目，支持按名称、数据集和详细程度（简化版 vs 完整版）进行可选过滤。 |
### 📊 数据集与示例
| 工具名称 | 描述 |
|-----------|-------------|
| `list_datasets` | 获取数据集，支持按 ID、类型、名称、名称子字符串或元数据进行过滤。 |
| `list_examples` | 通过数据集 ID/名称或示例 ID 从数据集中获取示例，支持过滤、元数据、splits 以及可选的 `as_of` 版本。 |
| `read_dataset` | 通过 ID 或名称读取单个数据集。 |
| `read_example` | 通过 ID 读取单个示例，支持可选的 `as_of` 版本。 |
| `create_dataset` | 仅作文档说明：如何在 LangSmith 中创建数据集。 |
| `update_examples` | 仅作文档说明：如何在 LangSmith 中更新数据集示例。 |
### 🧪 实验与评估
| 工具名称 | 描述 |
|-----------|-------------|
| `list_experiments` | 列出数据集的实验项目（参考项目）。需要 `reference_dataset_id` 或 `reference_dataset_name`。返回关键指标（延迟、成本、反馈统计）。 |
| `run_experiment` | 仅作文档说明：如何在 LangSmith 中运行实验和评估。 |
### 📈 使用量与账单
| 工具名称 | 描述 |
|-----------|-------------|
| `get_billing_usage` | 获取指定日期范围内的组织账单使用情况（例如 trace 计数）。支持可选的工作区过滤；返回指标并内联工作区名称。 |
### 📄 分页（基于字符）
多个工具使用**无状态、字符预算分页**机制，以确保响应保持在大小限制内，并与 LLM 客户端良好配合：
- **应用场景：** `get_thread_history` 和 `fetch_runs`（当设置了 `trace_id` 时）。
- **参数：** 每次请求都要发送 `page_number`（从 1 开始）。可选项：`max_chars_per_page`（默认 25000，上限 30000）和 `preview_chars`（使用 "… (+N chars)" 截断长字符串）。
- **响应：** 每个响应包含 `page_number`、`total_pages` 和页面 payload（消息对应 `result`，runs 对应 `runs`）。要获取更多内容，请再次调用并设置 `page_number = 2`，然后是 `3`，直到 `total_pages`。
- **优势：** 页面是基于 JSON 字符数构建的，而不是项目数量，因此每页都适合固定的大小。无需游标或服务端状态——只需整数页码。
## 🛠️ 安装选项
### 📝 常规前置条件
1. 安装 [uv](https://github.com/astral-sh/uv)（一个快速的 Python 包安装和解析工具）：
curl -LsSf https://astral.sh/uv/install.sh | sh
2. 克隆此仓库并导航至项目目录：
git clone https://github.com/langchain-ai/langsmith-mcp-server.git
cd langsmith-mcp-server
### 🔌 MCP 客户端集成
安装好 LangSmith MCP Server 后，您可以将其与各种兼容 MCP 的客户端集成。您有两种安装选项：
#### 📦 从 PyPI 安装
1. 安装该包：
uv run pip install --upgrade langsmith-mcp-server
2. 添加到您的客户端 MCP 配置中：
{
"mcpServers": {
"LangSmith API MCP Server": {
"command": "/path/to/uvx",
"args": [
"langsmith-mcp-server"
],
"env": {
"LANGSMITH_API_KEY": "your_langsmith_api_key",
"LANGSMITH_WORKSPACE_ID": "your_workspace_id",
"LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
}
}
}
}
#### ⚙️ 从源码安装
将以下配置添加到您的 MCP 客户端设置中（在**项目根目录**下运行，以便找到该包）：
```
{
"mcpServers": {
"LangSmith API MCP Server": {
"command": "/path/to/uv",
"args": [
"--directory",
"/path/to/langsmith-mcp-server",
"run",
"langsmith_mcp_server/server.py"
],
"env": {
"LANGSMITH_API_KEY": "your_langsmith_api_key",
"LANGSMITH_WORKSPACE_ID": "your_workspace_id",
"LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
}
}
}
}
```
替换以下占位符：
- `/path/to/uv`：您的 uv 安装路径的绝对路径（例如 `/Users/username/.local/bin/uv`）。您可以使用 `which uv` 找到它。
- `/path/to/langsmith-mcp-server`：**项目根目录**的绝对路径（即包含 `pyproject.toml` 和 `langsmith_mcp_server/` 的目录）。
- `your_langsmith_api_key`：您的 LangSmith API 密钥（必填）。
- `your_workspace_id`：您的 LangSmith 工作区 ID（可选，适用于分配给多个工作区的 API 密钥）。
- `https://api.smith.langchain.com`：LangSmith API endpoint（可选，默认为标准 endpoint）。
配置示例（PyPI/uvx）：
```
{
"mcpServers": {
"LangSmith API MCP Server": {
"command": "/path/to/uvx",
"args": ["langsmith-mcp-server"],
"env": {
"LANGSMITH_API_KEY": "lsv2_pt_your_key_here",
"LANGSMITH_WORKSPACE_ID": "your_workspace_id",
"LANGSMITH_ENDPOINT": "https://api.smith.langchain.com"
}
}
}
}
```
将此配置复制到 Cursor → MCP Settings 中（将 `/path/to/uvx` 替换为 `which uvx` 的输出结果）。
### 🔧 Headers（工具调用）
通过 **HTTP**（例如 streamable HTTP 或托管的 MCP endpoint）连接时，server 使用 **headers** 进行身份验证和配置。您的 MCP 客户端必须在每次请求时发送这些 headers；工具调用不需要环境变量。
| Header | 必填 | 描述 |
|--------|----------|-------------|
| `LANGSMITH-API-KEY` | ✅ 是 | 用于工具调用（列出 prompts、获取 runs 等）的 LangSmith API 密钥 |
| `LANGSMITH-WORKSPACE-ID` | ❌ 否 | 适用于分配给多个工作区的 API 密钥的工作区 ID |
| `LANGSMITH-ENDPOINT` | ❌ 否 | 自定义 API endpoint URL（适用于自托管或欧盟区域） |
仅在启用 [server 监控](#optional-tool-call-monitoring-to-a-second-langsmith-instance)时使用的可选 headers（用于按会话对 traces 进行分组）：
| Header | 描述 |
|--------|-------------|
| `mcp-session-id` | 会话或线程 ID；作为 `session_id` 存储在 trace 元数据中 |
| `x-session-id` | 如果未设置 `mcp-session-id`，则使用此项作为后备 |
| `x-request-id` | 用于请求范围分组的后备选项 |
**Stdio 传输：** 通过 stdio 运行 server 时（例如 `uvx langsmith-mcp-server`），没有 headers。server 会回退到进程环境变量中的 `LANGSMITH_API_KEY`、`LANGSMITH_WORKSPACE_ID` 和 `LANGSMITH_ENDPOINT`，以确保工具调用仍然有效。
### 🔧 环境变量
使用 HTTP 时，环境变量**不**用于工具调用（而是使用 headers）。它们用于：
1. **Stdio 传输** —— 在没有 headers 时的凭据后备（见上文）。
2. **负载测试** —— 例如 `tests/load_test_sessions.py` 会从环境（或项目根目录下的 `.env` 文件）中读取 `LANGSMITH_API_KEY`。
3. **可选的 server 监控** —— 将工具调用 tracing 到第二个 LangSmith 实例（见下文）。
| 变量 | 用途 | 描述 |
|----------|----------|-------------|
| `LANGSMITH_API_KEY` | Stdio 后备，负载测试 | LangSmith API 密钥（未通过 headers 提供时使用） |
| `LANGSMITH_WORKSPACE_ID` | Stdio 后备 | 工作区 ID（可选） |
| `LANGSMITH_ENDPOINT` | Stdio 后备 | 自定义 endpoint URL（可选） |
#### 可选：将工具调用监控发送到第二个 LangSmith 实例
| 变量 | 必填 | 描述 |
|----------|----------|-------------|
| `LANGSMITH_MONITORING_API_KEY` | 是（启用时） | 用于监控的 LangSmith 实例的 API 密钥 |
| `LANGSMITH_MONITORING_ENDPOINT` | 否 | Endpoint URL（默认：云端） |
| `LANGSMITH_MONITORING_WORKSPACE_ID` | 否 | 监控实例的工作区 ID |
| `LANGSMITH_MONITORING_PROJECT` | 否 | 监控 traces 的项目名称（默认：`mcp-server-monitoring`） |
| `LANGSMITH_TRACING` | 是（发送 traces 时） | 设置为 `true` 以便将 traces 发送到 LangSmith（[自定义插桩](https://docs.smith.langchain.com)） |
每次工具运行都会以 `run_type="tool"` 以及元数据中的 **session_id**（使用 HTTP 时来自 `mcp-session-id`、`x-session-id` 或 `x-request-id` header，或按请求生成）进行 trace。
如果您使用**托管版** LangSmith MCP Server，匿名的使用情况数据将被发送到单独的 LangSmith 项目中，以便我们不断迭代和改进产品。
## 🐳 Docker 部署 (HTTP-Streamable)
LangSmith MCP Server 可以使用 Docker 部署为 HTTP server，从而通过 HTTP-streamable 协议进行远程访问。
### 构建 Docker 镜像
```
docker build -t langsmith-mcp-server .
```
### 使用 Docker 运行
```
docker run -p 8000:8000 langsmith-mcp-server
```
连接时通过 `LANGSMITH-API-KEY` header 提供 API 密钥，因此 HTTP-streamable 协议不需要环境变量。
### 使用 HTTP-Streamable 协议连接
Docker 容器运行后，您可以使用 HTTP-streamable 传输连接到它。该 server 接受通过 headers 进行的身份验证：
**必填 header：**
- `LANGSMITH-API-KEY`：您的 LangSmith API 密钥
**可选 headers：**
-LANGSMITH-WORKSPACE-ID`：适用于分配给多个工作区的 API 密钥的工作区 ID
- `LANGSMITH-ENDPOINT`：自定义 endpoint URL（适用于自托管或欧盟区域）
**客户端配置示例：**
```
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
headers = {
"LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here",
# Optional:
# "LANGSMITH-WORKSPACE-ID": "your_workspace_id",
# "LANGSMITH-ENDPOINT": "https://api.smith.langchain.com",
}
async with streamablehttp_client("http://localhost:8000/mcp", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
# Use the session to call tools, list prompts, etc.
```
### Cursor 集成
要使用 HTTP-streamable 协议将 LangSmith MCP Server 添加到 Cursor，请将以下内容添加到您的 `mcp.json` 配置文件中：
```
{
"mcpServers": {
"HTTP-Streamable LangSmith MCP Server": {
"url": "http://localhost:8000/mcp",
"headers": {
"LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here"
}
}
}
}
```
**可选 headers：**
```
{
"mcpServers": {
"HTTP-Streamable LangSmith MCP Server": {
"url": "http://localhost:8000/mcp",
"headers": {
"LANGSMITH-API-KEY": "lsv2_pt_your_api_key_here",
"LANGSMITH-WORKSPACE-ID": "your_workspace_id",
"LANGSMITH-ENDPOINT": "https://api.smith.langchain.com"
}
}
}
}
```
在将 Cursor 连接到服务器之前，请确保服务器正在运行。
### 健康检查
该 server 提供一个健康检查 endpoint：
```
curl http://localhost:8000/health
```
此 endpoint 不需要身份验证，并在服务器健康时返回 `"LangSmith MCP server is running"`。
### 前置条件
- **Python** 3.10+（推荐 3.11+）
- **[uv](https://docs.astral.sh/uv/)** —— 使用 `curl -LsSf https://astral.sh/uv/install.sh | sh` 安装
- **LangSmith API 密钥** —— 获取自 [smith.langchain.com](https://smith.langchain.com)
- **Node.js**（可选）—— 仅当您想使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 测试 server（stdio 或 streamable-http）时需要
### 设置
```
git clone https://github.com/langchain-ai/langsmith-mcp-server.git
cd langsmith-mcp-server
uv sync # Install dependencies
uv sync --group test # Include test dependencies (pytest, ruff, mypy)
uvx langsmith-mcp-server # Verify CLI runs (stdio)
```
### 开发工作流
1. 在 `langsmith_mcp_server/` 或 `tests/` 中**编辑代码**。
2. **格式化和 lint**（提交前必须执行）：
make format
make lint
3. **运行测试**：
make test
# 或单个文件：
make test TEST_FILE=tests/tools/test_dataset_tools.py
4. **类型检查**（可选）：`uv run mypy langsmith_mcp_server/`
### 使用 MCP Inspector 进行测试
您可以使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 通过 **stdio** 或 **streamable-http** 测试 server。
1. **启动 MCP Inspector：**
npx @modelcontextprotocol/inspector@latest
在浏览器中打开 **http://localhost:6274**。
2. 在 Inspector 中**连接**：
- **Stdio：** 选择 stdio 传输并配置 server 命令（例如 `uv run langsmith-mcp-server`），并在环境中设置 `LANGSMITH_API_KEY`。
- **Streamable HTTP：** 首先启动 server（`uv run uvicorn langsmith_mcp_server.server:app --host 0.0.0.0 --port 8000` 或 Docker），然后选择 streamable-http，URL 为 **`http://localhost:8000/mcp`**，并添加 header **`LANGSMITH-API-KEY`** = 您的 API 密钥。
### 负载测试
**基于会话的**负载测试会打开许多 MCP 会话，并在每个会话中调用 `list_prompts` 工具，使用 [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters)。从 CLI 运行（无 UI）。必须先运行 server。
```
uv sync --group load
# Terminal 1：启动 server
uv run uvicorn langsmith_mcp_server.server:app --host 0.0.0.0 --port 8000
# Terminal 2：运行 load test
uv run python tests/load_test_sessions.py --sessions 20 --calls-per-session 3
```
**选项**
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `--url` | `http://localhost:8000/mcp` | MCP endpoint URL |
| `--api-key` | 取自 `.env` | `LANGSMITH_API_KEY`（或在项目根目录 `.env` 中设置） |
| `--sessions` | 10 | 并发会话数 |
| `--calls-per-session` | 3 | 每个会话的 `list_prompts` 调用次数 |
| `--debug` | 关闭 | 打印逐步日志和首次错误回溯信息 |
| `--report` PATH | — | 运行后写入报告（见下文） |
**报告**
使用 `--report PATH` 在测试后写入 JSON 报告（例如 `--report load_test_report` 会创建 `load_test_report.json`，包含配置、摘要、每个会话的结果以及首次错误）。
```
uv run python tests/load_test_sessions.py --sessions 5 --report load_test_report
# 创建：load_test_report.json（在当前目录）
```
## 📄 许可证
本项目基于 MIT 许可证分发。有关详细的条款和条件，请参阅 LICENSE 文件。
由 [LangChain](https://langchain.com) 团队用 ❤️ 制作
标签：API集成, DLL 劫持, MCP服务, SOC Prime, 人工智能, 可观测性, 大语言模型, 开发工具, 用户模式Hook绕过, 请求拦截, 逆向工具