Meta Agent Tools
PT

Back to the catalog

io.github.salted-butter-joshua/dify-mcp

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

Open source Open in the app JSON README (API)

About

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

Details

Kind
MCP servers
Topic
AI, RAG & memory
Publisher
salted-butter-joshua
Origin
official
Category
ferramentas
Transport
local
Version
0.1.0
Last push
2026-07-05T12:12:28Z
Repository state
ativo
Language
Python
License
MIT
Added
2026-08-29 04:01:21
Updated
2026-08-29 04:01:21
Origin id
io.github.salted-butter-joshua/dify-mcp

README

# dify-mcp

<!-- mcp-name: io.github.salted-butter-joshua/dify-mcp -->

Expose [Dify](https://dify.ai) knowledge base retrieval capabilities via [MCP](https://modelcontextprotocol.io) (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:

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

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`](mcp.json.example) for a full example.

**Windows example:**

```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:**

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

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)](https://docs.dify.ai/api-reference/knowledge-bases/list-knowledge-bases)
- [Retrieve chunks](https://docs.dify.ai/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval)
- Local path reference: [`Dify-API.md`](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

More