dify-mcp

dify-mcp

通过 MCP（Model Context Protocol）开放 Dify 知识库检索功能，供 Cursor 和其他兼容 MCP 的客户端使用。

通过 HTTP 连接到自托管或远程 Dify 实例，并可选择启用数据集允许列表进行访问控制。

功能

• 知识库发现 — 列出并检查允许访问的数据集
• 语义检索 — 通过 Dify POST /datasets/{dataset_id}/retrieve 搜索文本块
• 文档浏览 — 列出数据集中的文档和片段
• 数据集允许列表 — 将访问限制为特定的 dataset_id 值
• stdio 传输 — 无需手动启动服务；MCP 客户端会启动进程

要求

• Python 3.11+
• 正在运行且已启用知识库 API 的 Dify 实例
• 运行 MCP 服务的计算机能够访问 Dify API 端点
• Dify 知识库 API 密钥（Dify → 知识 → 服务 API → API 密钥）

快速开始

1. 克隆并安装

git clone https://github.com/salted-butter-joshua/dify-mcp.git
cd dify-mcp

python3.11 -m venv .venv

# Windows
.venv\Scripts\python.exe -m pip install -e .

# macOS / Linux
.venv/bin/python -m pip install -e .

验证导入：

# Windows
.venv\Scripts\python.exe -c "import dify_mcp; print('OK')"

# macOS / Linux
.venv/bin/python -c "import dify_mcp; print('OK')"

2. 配置环境

复制示例环境文件并进行编辑：

cp .env.example .env

DIFY_API_BASE=http://your-dify-host/v1
DIFY_API_KEY=dataset-your-api-key
DIFY_ALLOWED_DATASETS=dataset-uuid-1,dataset-uuid-2
DIFY_TIMEOUT=30
DIFY_VERIFY_SSL=false

变量	描述
DIFY_API_BASE	Dify 知识库 API 基础 URL，例如 http://192.168.1.100/v1
DIFY_API_KEY	知识库 API 密钥
DIFY_ALLOWED_DATASETS	要开放的逗号分隔数据集 UUID（必填）
DIFY_TIMEOUT	HTTP 超时秒数（默认值：30）
DIFY_VERIFY_SSL	验证 TLS 证书（对于自签名证书，默认值：false）

运行健康检查：

# Windows
.venv\Scripts\python.exe scripts/health_check.py

# macOS / Linux
.venv/bin/python scripts/health_check.py

3. 添加到 Cursor

无需手动启动 MCP 服务。Cursor 会通过 stdio 自动启动它。

1. 打开 Cursor 设置 → MCP → 编辑配置
2. 在 MCP 配置文件的 mcpServers 中添加以下内容：
   • Windows：%USERPROFILE%\.cursor\mcp.json
   • macOS / Linux：~/.cursor/mcp.json
3. 将路径和环境变量值替换为你自己的值
4. 重启 Cursor

完整示例请参见 mcp.json.example。

Windows 示例：

{
  "mcpServers": {
    "dify-knowledge": {
      "command": "/absolute/path/to/dify-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "dify_mcp.server"],
      "cwd": "/absolute/path/to/dify-mcp",
      "env": {
        "DIFY_API_BASE": "http://your-dify-host/v1",
        "DIFY_API_KEY": "dataset-your-api-key",
        "DIFY_ALLOWED_DATASETS": "dataset-uuid-1,dataset-uuid-2",
        "DIFY_TIMEOUT": "30",
        "DIFY_VERIFY_SSL": "false"
      }
    }
  }
}

macOS / Linux 示例：

{
  "mcpServers": {
    "dify-knowledge": {
      "command": "/absolute/path/to/dify-mcp/.venv/bin/python",
      "args": ["-m", "dify_mcp.server"],
      "cwd": "/absolute/path/to/dify-mcp",
      "env": {
        "DIFY_API_BASE": "http://your-dify-host/v1",
        "DIFY_API_KEY": "dataset-your-api-key",
        "DIFY_ALLOWED_DATASETS": "dataset-uuid-1,dataset-uuid-2"
      }
    }
  }
}

4. 在 Cursor 中验证

1. Cursor 设置 → MCP → 确认 dify-knowledge 显示为已启用
2. 在聊天中尝试：
   • 列出可用的 Dify 知识库
   • 在知识库中搜索“你的查询”

MCP 工具

工具	描述
list_datasets	列出允许列表中的知识库
get_dataset	获取单个数据集的元数据
search_knowledge	检索相关文本块（主要检索工具）
list_documents	列出数据集中的文档
list_document_segments	列出文档的文本片段

架构

Cursor (MCP client)
    │ stdio
    ▼
dify-mcp (local process)
    │ HTTPS / HTTP
    ▼
Dify Knowledge API (/v1/datasets/...)

MCP 服务在你的计算机本地运行，并通过网络调用 Dify API。Dify 无需连接到你的计算机。

故障排除

问题	原因	解决方法
No matching distribution found for mcp	Python < 3.11	在 .venv 中使用 Python 3.11+
MCP 显示错误（红色）	Python 路径错误、密钥无效或网络问题	检查 mcp.json 路径和环境变量
401 Unauthorized	API 密钥无效	在 Dify 服务 API 面板中重新生成密钥
Dataset not in allowed list	UUID 不在 DIFY_ALLOWED_DATASETS 中	将数据集 UUID 添加到允许列表
健康检查提示缺少环境变量	找不到 .env	确保项目根目录中存在 .env
连接超时	无法访问 Dify	检查网络 / VPN / 防火墙

项目结构

dify-mcp/
├── src/dify_mcp/
│   ├── server.py        # MCP entry point
│   ├── config.py        # Settings and allowlist
│   ├── dify_client.py   # Dify Knowledge API client
│   └── formatters.py    # Response formatting
├── scripts/
│   └── health_check.py  # Connectivity test
├── mcp.json.example     # Cursor MCP config template
├── .env.example         # Environment variable template
└── Dify-API.md          # Local API path reference

API 参考

• Dify 知识库 API（官方）
• 检索文本块
• 本地路径参考：Dify-API.md

安全说明

• 切勿将 .env 或 API 密钥提交到版本控制中
• 单个 Knowledge Base API 密钥可以访问账户下所有可见的数据集 — 使用 DIFY_ALLOWED_DATASETS 限制暴露范围
• 优先在本地运行 MCP；仅在本机的 mcp.json 环境变量或 .env 中保存 API 密钥