Dify MCP

MCP server exposing Dify knowledge base retrieval to Cursor and other MCP clients

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "dify-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dify-mcp"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Dify MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "dify-mcp": { "command": "npx", "args": ["-y", "dify-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/dify-mcp?style=directory)](https://allmcps.com/mcp/dify-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/dify-mcp"><img src="https://allmcps.com/api/badge/dify-mcp?style=directory" alt="Dify MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Dify MCP →Install in Claude Desktop Install in Cursor Install in VS Code

Dify MCP

MCP server exposing Dify knowledge base retrieval to Cursor and other MCP clients

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "dify-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "dify-mcp"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Dify MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "dify-mcp": { "command": "npx", "args": ["-y", "dify-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/dify-mcp?style=directory)](https://allmcps.com/mcp/dify-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/dify-mcp"><img src="https://allmcps.com/api/badge/dify-mcp?style=directory" alt="Dify MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to Dify MCP →Install in Claude Desktop Install in Cursor Install in VS Code