内容
[**中文**](README.md)
# Dify 管理 MCP 服务器
一个用于直接从 Claude Code 终端管理 Dify AI 工作流的 MCP（模型上下文协议）服务器。
无需 Dify 的可视化界面 — 您可以通过 Claude Code 直接创建、编辑、测试和发布工作流。
## 需求
- [uv](https://docs.astral.sh/uv/)（Python 包管理器）
- [Claude Code](https://claude.ai/claude-code) 命令行界面
- 一个正在运行的 [Dify](https://github.com/langgenius/dify) 实例（通过 Docker Compose）
## 设置
### 1. 克隆仓库
```bash
git clone <仓库网址> dify-mcp-server
cd dify-mcp-server
```
### 2. 安装 uv（如果尚未安装）
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 3. 在 Dify 中启用管理员 API 密钥
在 Dify 的 `docker/.env` 文件中添加以下内容：
```ini
ADMIN_API_KEY_ENABLE=true
ADMIN_API_KEY=<生成一个强密钥>
```
要生成密钥：
```bash
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```
**重要：** 将这两行添加到 Dify 的 `docker/docker-compose.yaml` 中的 `x-shared-env` 块中（否则环境变量不会传递给容器）：
```yaml
x-shared-env: &shared-api-worker-env
# ... 现有值 ...
ADMIN_API_KEY_ENABLE: ${ADMIN_API_KEY_ENABLE:-false}
ADMIN_API_KEY: ${ADMIN_API_KEY:-}
```
然后重启容器：
```bash
cd docker
docker compose down && docker compose up -d
```
### 4. 获取您的 Workspace ID
登录到 Dify 后：
```bash
# 首先，登录（密码必须进行 base64 编码）
B64PASS=$(echo -n "<您的密码>" | base64)
curl -s -c /tmp/cookies.txt -X POST http://localhost/console/api/login \
-H "Content-Type: application/json" \
-d "{\"email\":\"<邮箱>\",\"password\":\"$B64PASS\"}"
# 获取 CSRF token
CSRF=$(grep csrf_token /tmp/cookies.txt | awk '{print $NF}')
# 获取工作区列表
curl -s -b /tmp/cookies.txt "http://localhost/console/api/workspaces" \
-H "X-Csrf-Token: $CSRF"
```
输出中的 `"id"` 值是您的 Workspace ID。
### 5. 在 Claude Code 中注册 MCP 服务器
在 `~/.claude.json`（或项目级 `settings.json`）中将以下内容添加到 `"mcpServers"` 部分：
```json
{
"mcpServers": {
"dify-manager": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--project", "/完整/路径/到/dify-mcp-server",
"python", "/完整/路径/到/dify-mcp-server/server.py"
],
"env": {
"DIFY_BASE_URL": "http://localhost",
"DIFY_ADMIN_API_KEY": "<您的管理员 API 密钥>",
"DIFY_WORKSPACE_ID": "<您的工作区 ID>"
}
}
}
}
```
> 将 `/完整/路径/到/dify-mcp-server` 替换为克隆目录的完整路径。
### 6. 重启 Claude Code
```bash
claude
```
## 使用
您可以在 Claude Code 终端中给出自然语言命令：
```
> 列出 Dify 中的应用
> 将“客户支持”应用导出为 YAML 并保存到 workflow.yaml
> 在此工作流中添加一个执行情感分析的 Python 节点
> 将更改推送到 Dify 并使用输入“Hello, I was very frustrated!”进行测试
> 发布草稿
```
## 功能
- **Dify-as-Code：** 将工作流导出为 YAML，编辑，恢复 — 使用 Git 进行版本控制
- **一键测试：** 在测试模式下运行工作流或单个节点，立即查看结果
- **批量测试：** 一次运行多个测试用例，比较成功率
- **知识库管理：** 创建数据集，上传文档，测试 RAG 检索
- **模型和工具管理：** 列出模型提供商和工具，设置默认模型
- **统计和日志：** Token 成本，每日使用情况，响应时间，错误率
- **健康检查：** 一次检查所有应用的状态
- **DSL 比较：** 比较两个 YAML 版本的差异
- **批量导出：** 将所有应用导出为 YAML 文件
## MCP 工具（52 个工具）
### 应用管理
| 工具 | 描述 |
|---|---|
| `list_apps` | 列出所有应用（带有分页和过滤） |
| `get_app_detail` | 获取应用详情 |
| `create_app` | 创建一个新的空应用 |
| `delete_app` | 删除应用 |
| `copy_app` | 复制现有应用 |
### DSL 导出/导入
| 工具 | 描述 |
|---|---|
| `get_app_dsl` | 将工作流导出为 YAML DSL |
| `update_app_dsl` | 将 YAML DSL 导入/更新到 Dify |
### 工作流管理
| 工具 | 描述 |
|---|---|
| `get_workflow_draft` | 获取草稿图结构（节点，边） |
| `publish_workflow` | 将草稿发布为活动版本 |
| `list_workflow_versions` | 列出所有已发布的工作流版本 |
| `restore_workflow_version` | 恢复以前的版本 |
| `run_workflow_test` | 在测试模式下运行草稿工作流 |
| `run_single_node` | 测试单个节点 |
| `stop_workflow_task` | 停止正在运行的工作流 |
| `get_default_block_configs` | 按节点类型获取默认配置 |
### 日志和运行历史
| 工具 | 描述 |
|---|---|
| `get_workflow_runs` | 列出工作流运行历史 |
| `get_workflow_run_detail` | 获取特定运行的详细信息 |
| `get_node_executions` | 获取节点级执行详细信息 |
| `get_workflow_app_logs` | 获取应用日志 |
### 统计
| 工具 | 描述 |
|---|---|
| `get_app_statistics` | 消息，用户，token，成本，响应时间统计 |
| `get_workflow_statistics` | 工作流特定的运行和成本统计 |
### 知识库
| 工具 | 描述 |
|---|---|
| `list_datasets` | 列出所有数据集 |
| `create_dataset` | 创建新的数据集 |
| `get_dataset_detail` | 获取数据集详情 |
| `delete_dataset` | 删除数据集 |
| `list_documents` | 列出数据集中的文档 |
| `get_document_segments` | 列出文档块 |
| `get_dataset_indexing_status` | 显示索引状态 |
| `hit_testing` | RAG 检索测试 — 查找与查询匹配的块 |
| `get_dataset_related_apps` | 显示使用数据集的应用 |
### 模型提供商管理
| 工具 | 描述 |
|---|---|
| `list_model_providers` | 列出所有模型提供商 |
| `get_provider_models` | 列出提供商的模型 |
| `get_default_model` | 显示默认模型 |
| `set_default_model` | 设置默认模型 |
### 工具提供商管理
| 工具 | 描述 |
|---|---|
| `list_tool_providers` | 列出所有工具提供商 |
| `list_builtin_tools` | 列出提供商的工具 |
| `list_workflow_tools` | 列出工作流即工具定义 |
### 环境变量
| 工具 | 描述 |
|---|---|
| `get_environment_variables` | 获取工作流环境变量 |
| `get_conversation_variables` | 获取对话变量 |
### API 密钥管理
| 工具 | 描述 |
|---|---|
| `list_app_api_keys` | 列出应用 API 密钥 |
| `create_app_api_key` | 创建新的 API 密钥 |
| `delete_app_api_key` | 删除 API 密钥 |
### 标签
| 工具 | 描述 |
|---|---|
| `list_tags` | 列出所有标签 |
| `create_tag` | 创建新的标签 |
### 对话和消息
| 工具 | 描述 |
|---|---|
| `list_conversations` | 列出聊天对话 |
| `list_messages` | 列出消息 |
### 访问控制
| 工具 | 描述 |
|---|---|
| `toggle_app_site` | 启用/禁用 Web 接口访问 |
| `toggle_app_api` | 启用/禁用 API 访问 |
### 高级工具
| 工具 | 描述 |
|---|---|
| `dsl_diff` | 比较两个 YAML DSL，显示差异 |
| `batch_test` | 批量运行多个测试用例 |
| `health_check` | 检查所有应用的状态和错误率 |
| `export_all_apps_dsl` | 将所有应用批量导出为 YAML 文件 |
## 环境变量
| 变量 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|
| `DIFY_BASE_URL` | 否 | `http://localhost` | Dify 实例 URL |
| `DIFY_ADMIN_API_KEY` | 是 | - | Dify 管理员 API 密钥 |
| `DIFY_WORKSPACE_ID` | 是 | - | Dify 工作区 UUID |
## 架构
```
Claude Code <--> MCP 服务器（stdio） <--> Dify 控制台 API
（此项目） （localhost/console/api）
|
Dify 平台
（Docker Compose）
```
MCP 服务器使用 `Authorization: Bearer <管理员 API 密钥>` 和 `X-WORKSPACE-ID` 头与 Dify 控制台 API 连接。不需要 cookie/CSRF。
## 故障排除
**“未找到 ADMIN_API_KEY 环境变量”**
- 检查 `settings.json` 中的 `env` 块是否正确。
**“401 未授权” / “无效令牌”**
- 确保 `ADMIN_API_KEY` 和 `ADMIN_API_KEY_ENABLE` 行在 `docker-compose.yaml` 中位于 `x-shared-env` 下。
- 使用 `docker compose down && docker compose up -d` 重启。
- 在容器内检查环境变量：`docker compose exec api env | grep ADMIN`
**“CSRF 令牌丢失”**
- 管理员 API 密钥未正确配置。请检查上述步骤。
## 许可证
MIT
