{
  "markdown": "# dify-mcp\r\n\r\n<!-- mcp-name: io.github.salted-butter-joshua/dify-mcp -->\r\n\r\nExpose [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.\r\n\r\nConnect to a self-hosted or remote Dify instance over HTTP, with optional dataset allowlisting for access control.\r\n\r\n## Features\r\n\r\n- **Knowledge base discovery** — list and inspect allowed datasets\r\n- **Semantic retrieval** — search chunks via Dify `POST /datasets/{dataset_id}/retrieve`\r\n- **Document browsing** — list documents and segments within a dataset\r\n- **Dataset allowlist** — restrict access to specific `dataset_id` values\r\n- **stdio transport** — no manual server startup; the MCP client launches the process\r\n\r\n## Requirements\r\n\r\n- Python **3.11+**\r\n- A running Dify instance with Knowledge Base API enabled\r\n- Network access from the machine running the MCP server to your Dify API endpoint\r\n- A Dify **Knowledge Base API Key** (Dify → Knowledge → Service API → API Key)\r\n\r\n## Quick Start\r\n\r\n### 1. Clone and install\r\n\r\n```bash\r\ngit clone https://github.com/salted-butter-joshua/dify-mcp.git\r\ncd dify-mcp\r\n\r\npython3.11 -m venv .venv\r\n\r\n# Windows\r\n.venv\\Scripts\\python.exe -m pip install -e .\r\n\r\n# macOS / Linux\r\n.venv/bin/python -m pip install -e .\r\n```\r\n\r\nVerify import:\r\n\r\n```bash\r\n# Windows\r\n.venv\\Scripts\\python.exe -c \"import dify_mcp; print('OK')\"\r\n\r\n# macOS / Linux\r\n.venv/bin/python -c \"import dify_mcp; print('OK')\"\r\n```\r\n\r\n### 2. Configure environment\r\n\r\nCopy the example env file and edit it:\r\n\r\n```bash\r\ncp .env.example .env\r\n```\r\n\r\n```env\r\nDIFY_API_BASE=http://your-dify-host/v1\r\nDIFY_API_KEY=dataset-your-api-key\r\nDIFY_ALLOWED_DATASETS=dataset-uuid-1,dataset-uuid-2\r\nDIFY_TIMEOUT=30\r\nDIFY_VERIFY_SSL=false\r\n```\r\n\r\n| Variable | Description |\r\n|----------|-------------|\r\n| `DIFY_API_BASE` | Dify Knowledge API base URL, e.g. `http://192.168.1.100/v1` |\r\n| `DIFY_API_KEY` | Knowledge Base API key |\r\n| `DIFY_ALLOWED_DATASETS` | Comma-separated dataset UUIDs to expose (required) |\r\n| `DIFY_TIMEOUT` | HTTP timeout in seconds (default: `30`) |\r\n| `DIFY_VERIFY_SSL` | Verify TLS certificates (default: `false` for self-signed certs) |\r\n\r\nRun the health check:\r\n\r\n```bash\r\n# Windows\r\n.venv\\Scripts\\python.exe scripts/health_check.py\r\n\r\n# macOS / Linux\r\n.venv/bin/python scripts/health_check.py\r\n```\r\n\r\n### 3. Add to Cursor\r\n\r\nYou do **not** need to start the MCP server manually. Cursor launches it automatically via stdio.\r\n\r\n1. Open Cursor Settings → **MCP** → **Edit config**\r\n2. Add the following to `mcpServers` in your MCP config file:\r\n   - Windows: `%USERPROFILE%\\.cursor\\mcp.json`\r\n   - macOS / Linux: `~/.cursor/mcp.json`\r\n3. Replace paths and env values with your own\r\n4. Restart Cursor\r\n\r\nSee [`mcp.json.example`](mcp.json.example) for a full example.\r\n\r\n**Windows example:**\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"dify-knowledge\": {\r\n      \"command\": \"/absolute/path/to/dify-mcp/.venv/Scripts/python.exe\",\r\n      \"args\": [\"-m\", \"dify_mcp.server\"],\r\n      \"cwd\": \"/absolute/path/to/dify-mcp\",\r\n      \"env\": {\r\n        \"DIFY_API_BASE\": \"http://your-dify-host/v1\",\r\n        \"DIFY_API_KEY\": \"dataset-your-api-key\",\r\n        \"DIFY_ALLOWED_DATASETS\": \"dataset-uuid-1,dataset-uuid-2\",\r\n        \"DIFY_TIMEOUT\": \"30\",\r\n        \"DIFY_VERIFY_SSL\": \"false\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**macOS / Linux example:**\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"dify-knowledge\": {\r\n      \"command\": \"/absolute/path/to/dify-mcp/.venv/bin/python\",\r\n      \"args\": [\"-m\", \"dify_mcp.server\"],\r\n      \"cwd\": \"/absolute/path/to/dify-mcp\",\r\n      \"env\": {\r\n        \"DIFY_API_BASE\": \"http://your-dify-host/v1\",\r\n        \"DIFY_API_KEY\": \"dataset-your-api-key\",\r\n        \"DIFY_ALLOWED_DATASETS\": \"dataset-uuid-1,dataset-uuid-2\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### 4. Verify in Cursor\r\n\r\n1. Cursor Settings → **MCP** → confirm `dify-knowledge` shows as enabled\r\n2. In chat, try:\r\n   - *List available Dify knowledge bases*\r\n   - *Search the knowledge base for \"your query\"*\r\n\r\n## MCP Tools\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `list_datasets` | List knowledge bases within the allowlist |\r\n| `get_dataset` | Get metadata for one dataset |\r\n| `search_knowledge` | Retrieve relevant chunks (primary retrieval tool) |\r\n| `list_documents` | List documents in a dataset |\r\n| `list_document_segments` | List text segments for a document |\r\n\r\n## Architecture\r\n\r\n```\r\nCursor (MCP client)\r\n    │ stdio\r\n    ▼\r\ndify-mcp (local process)\r\n    │ HTTPS / HTTP\r\n    ▼\r\nDify Knowledge API (/v1/datasets/...)\r\n```\r\n\r\nThe MCP server runs locally on your machine and calls the Dify API over the network. Dify does not need to reach your machine.\r\n\r\n## Troubleshooting\r\n\r\n| Issue | Cause | Fix |\r\n|-------|-------|-----|\r\n| `No matching distribution found for mcp` | Python < 3.11 | Use Python 3.11+ in `.venv` |\r\n| MCP shows error (red) | Wrong Python path, invalid key, or network issue | Check `mcp.json` paths and env vars |\r\n| `401 Unauthorized` | Invalid API key | Regenerate key in Dify Service API panel |\r\n| `Dataset not in allowed list` | UUID not in `DIFY_ALLOWED_DATASETS` | Add the dataset UUID to the allowlist |\r\n| Health check missing env vars | `.env` not found | Ensure `.env` exists in the project root |\r\n| Connection timeout | Dify unreachable | Check network / VPN / firewall |\r\n\r\n## Project Structure\r\n\r\n```\r\ndify-mcp/\r\n├── src/dify_mcp/\r\n│   ├── server.py        # MCP entry point\r\n│   ├── config.py        # Settings and allowlist\r\n│   ├── dify_client.py   # Dify Knowledge API client\r\n│   └── formatters.py    # Response formatting\r\n├── scripts/\r\n│   └── health_check.py  # Connectivity test\r\n├── mcp.json.example     # Cursor MCP config template\r\n├── .env.example         # Environment variable template\r\n└── Dify-API.md          # Local API path reference\r\n```\r\n\r\n## API Reference\r\n\r\n- [Dify Knowledge Base API (official)](https://docs.dify.ai/api-reference/knowledge-bases/list-knowledge-bases)\r\n- [Retrieve chunks](https://docs.dify.ai/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval)\r\n- Local path reference: [`Dify-API.md`](Dify-API.md)\r\n\r\n## Security Notes\r\n\r\n- Never commit `.env` or API keys to version control\r\n- A single Knowledge Base API key can access all visible datasets under the account — use `DIFY_ALLOWED_DATASETS` to limit exposure\r\n- Prefer running MCP locally; keep API keys in `mcp.json` env or `.env` on your machine only\r\n",
  "bytes": 6482,
  "sha": "4f5440bc7374ed2f76e8b6a8f6e0b176f4b116e2be66346d296654289e1d2171",
  "repo_slug": "salted-butter-joshua/dify-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_salted_butter_joshua_dify_mcp_80b7fe2d/readme"
}