dify-mcp

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

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