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

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
3. Replace paths and env values with your own
4. 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

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

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