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

bash

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:

server.ts

# 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:

bash

cp .env.example .env

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:

bash

# 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.

Open Cursor Settings → MCP → Edit config
Add the following to mcpServers in your MCP config file:
- Windows: %USERPROFILE%\.cursor\mcp.json
- macOS / Linux: ~/.cursor/mcp.json
Replace paths and env values with your own
Restart Cursor

See mcp.json.example for a full example.

Windows example:

config.json

{

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

config.json

{

  "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

Cursor Settings → MCP → confirm dify-knowledge shows as enabled
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

Code

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

Code

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

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