Dify MCP server

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

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

Shortened. The full README is on GitHub.