dify-knowledge

dify-mcp

<!-- mcp-name: io.github.salted-butter-joshua/dify-mcp -->

Expose Dify knowledge base retrieval capabilities via MCP (Model Context Protocol), for use in Cursor and other MCP-compatible clients.

Connect to a self-hosted or remote Dify instance over HTTP, with optional dataset allowlisting for access control.

Features

• Knowledge base discovery — list and inspect allowed datasets
• Semantic retrieval — search chunks via Dify POST /datasets/{dataset_id}/retrieve
• Document browsing — list documents and segments within a dataset
• Dataset allowlist — restrict access to specific dataset_id values
• stdio transport — no manual server startup; the MCP client launches the process

Requirements

• Python 3.11+
• A running Dify instance with Knowledge Base API enabled
• Network access from the machine running the MCP server to your Dify API endpoint
• A Dify Knowledge Base API Key (Dify → Knowledge → Service API → API Key)

Quick Start

1. Clone and install

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 .

Verify import:

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

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

2. Configure environment

Copy the example env file and edit it:

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

| Variable | Description | |----------|-------------| | DIFY_API_BASE | Dify Knowledge API base URL, e.g. http://192.168.1.100/v1 | | DIFY_API_KEY | Knowledge Base API key | | DIFY_ALLOWED_DATASETS | Comma-separated dataset UUIDs to expose (required) | | DIFY_TIMEOUT | HTTP timeout in seconds (default: 30) | | DIFY_VERIFY_SSL | Verify TLS certificates (default: false for self-signed certs) |

Run the health check:

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

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

3. Add to Cursor

You do not need to start the MCP server manually. Cursor launches it automatically via stdio.

1. Open Cursor Settings → MCP → Edit config
2. Add the following to mcpServers in your MCP config file:

• Windows: %USERPROFILE%\.cursor\mcp.json
• macOS / Linux: ~/.cursor/mcp.json

1. Replace paths and env values with your own
2. Restart Cursor

See mcp.json.example for a full example.

Windows example:

{
  "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 example:

{
  "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. Verify in Cursor

1. Cursor Settings → MCP → confirm dify-knowledge shows as enabled
2. In chat, try:

• List available Dify knowledge bases
• Search the knowledge base for "your query"

MCP Tools

| Tool | Description | |------|-------------| | list_datasets | List knowledge bases within the allowlist | | get_dataset | Get metadata for one dataset | | search_knowledge | Retrieve relevant chunks (primary retrieval tool) | | list_documents | List documents in a dataset | | list_document_segments | List text segments for a document |

Architecture

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

The MCP server runs locally on your machine and calls the Dify API over the network. Dify does not need to reach your machine.

Troubleshooting

| Issue | Cause | Fix | |-------|-------|-----| | No matching distribution found for mcp | Python < 3.11 | Use Python 3.11+ in .venv | | MCP shows error (red) | Wrong Python path, invalid key, or network issue | Check mcp.json paths and env vars | | 401 Unauthorized | Invalid API key | Regenerate key in Dify Service API panel | | Dataset not in allowed list | UUID not in DIFY_ALLOWED_DATASETS | Add the dataset UUID to the allowlist | | Health check missing env vars | .env not found | Ensure .env exists in the project root | | Connection timeout | Dify unreachable | Check network / VPN / firewall |

Project Structure

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 Reference

• Dify Knowledge Base API (official)
• Retrieve chunks
• Local path reference: Dify-API.md

Security Notes

• Never commit .env or API keys to version control
• A single Knowledge Base API key can access all visible datasets under the account — use DIFY_ALLOWED_DATASETS to limit exposure
• Prefer running MCP locally; keep API keys in mcp.json env or .env on your machine only