dify-mcp

dify-mcp

Cursor やその他の MCP 対応クライアントで使用するために、Dify のナレッジベース検索機能を MCP（Model Context Protocol）経由で公開します。

HTTP 経由でセルフホストまたはリモートの Dify インスタンスに接続し、アクセス制御のためにデータセットの許可リストを任意で設定できます。

機能

• ナレッジベースの検出 — 許可されたデータセットを一覧表示して確認します
• セマンティック検索 — Dify POST /datasets/{dataset_id}/retrieve を使用してチャンクを検索します
• ドキュメントの閲覧 — データセット内のドキュメントとセグメントを一覧表示します
• データセットの許可リスト — アクセスを特定の dataset_id 値に制限します
• stdio トランスポート — サーバーを手動で起動する必要はありません。MCP クライアントがプロセスを起動します

要件

• Python 3.11+
• Knowledge Base API が有効な、稼働中の Dify インスタンス
• MCP サーバーを実行するマシンから Dify API エンドポイントへのネットワークアクセス
• Dify の Knowledge Base API Key（Dify → Knowledge → Service API → API Key）

クイックスタート

1. クローンしてインストール

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 .

インポートを確認します：

# Windows
.venv\Scripts\python.exe -c "import dify_mcp; print('OK')"

# macOS / Linux
.venv/bin/python -c "import dify_mcp; print('OK')"

2. 環境を設定

サンプル env ファイルをコピーして編集します：

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

変数	説明
DIFY_API_BASE	Dify Knowledge API のベース URL。例：http://192.168.1.100/v1
DIFY_API_KEY	Knowledge Base API キー
DIFY_ALLOWED_DATASETS	公開するデータセット UUID（カンマ区切り、必須）
DIFY_TIMEOUT	HTTP タイムアウト（秒、デフォルト：30）
DIFY_VERIFY_SSL	TLS 証明書を検証するかどうか（自己署名証明書の場合のデフォルト：false）

ヘルスチェックを実行します：

# Windows
.venv\Scripts\python.exe scripts/health_check.py

# macOS / Linux
.venv/bin/python scripts/health_check.py

3. Cursor に追加

MCP サーバーを手動で起動する必要はありません。Cursor が stdio 経由で自動的に起動します。

1. Cursor Settings → MCP → Edit config を開きます
2. MCP 設定ファイルの mcpServers に以下を追加します：
   • Windows：%USERPROFILE%\.cursor\mcp.json
   • macOS / Linux：~/.cursor/mcp.json
3. パスと env 値を自分の環境に合わせて置き換えます
4. Cursor を再起動します

全体の例は mcp.json.example を参照してください。

Windows の例：

{
  "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 の例：

{
  "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. Cursor で確認

1. Cursor Settings → MCP → dify-knowledge が有効と表示されていることを確認します
2. チャットで次を試します：
   • 利用可能な Dify ナレッジベースを一覧表示して
   • 「your query」でナレッジベースを検索して

MCP ツール

ツール	説明
list_datasets	許可リスト内のナレッジベースを一覧表示します
get_dataset	1 つのデータセットのメタデータを取得します
search_knowledge	関連するチャンクを取得します（主要な検索ツール）
list_documents	データセット内のドキュメントを一覧表示します
list_document_segments	ドキュメントのテキストセグメントを一覧表示します

アーキテクチャ

Cursor (MCP client)
    │ stdio
    ▼
dify-mcp (local process)
    │ HTTPS / HTTP
    ▼
Dify Knowledge API (/v1/datasets/...)

MCP サーバーはマシン上でローカルに実行され、ネットワーク経由で Dify API を呼び出します。Dify からお使いのマシンに接続する必要はありません。

トラブルシューティング

問題	原因	対処方法
No matching distribution found for mcp	Python < 3.11	.venv で Python 3.11+ を使用します
MCP にエラー（赤色）が表示される	Python のパスが誤っている、キーが無効、またはネットワークの問題	mcp.json のパスと env 変数を確認します
401 Unauthorized	API キーが無効	Dify Service API パネルでキーを再生成します
Dataset not in allowed list	UUID が DIFY_ALLOWED_DATASETS に含まれていない	データセット UUID を許可リストに追加します
ヘルスチェックで環境変数が見つからない	.env が見つからない	プロジェクトのルートに .env があることを確認します
接続タイムアウト	Dify に接続できない	ネットワーク／VPN／ファイアウォールを確認します

プロジェクト構成

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 リファレンス

• Dify Knowledge Base API（公式）
• チャンクの取得
• ローカルパスのリファレンス：Dify-API.md

セキュリティに関する注意事項

• .env や API キーをバージョン管理にコミットしないでください
• 1 つの Knowledge Base API キーで、アカウント内のすべての表示可能なデータセットにアクセスできます。公開範囲を制限するには DIFY_ALLOWED_DATASETS を使用してください
• MCP はローカルで実行することを推奨します。API キーは、ご自身のマシン上の mcp.json の env または .env にのみ保存してください