# 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