Desearch

Desearch MCP Server

Desearch が役に立った場合は、スターを付けると、ほかの人にも見つけてもらいやすくなります。

リモート：https://mcp.desearch.ai/mcp に、ヘッダー Authorization: Bearer <DESEARCH_API_KEY> を指定します。

ローカル：npx -y desearch-mcp-server@latest を、環境変数 DESEARCH_API_KEY とともに実行します。

キーを取得。

Desearch の掲載先

• 公式 MCP Registry
• Smithery
• Glama
• VoltAgent 公式 MCP サーバー
• Gemini CLI 拡張機能
• Raycast MCP Registry

デモ

プロンプト：AI に関する最新ニュースをウェブで検索してください。

web-search は、query（必須）と start（任意のページネーションオフセット：0、10、20、…）を受け取ります。

{
    "name": "web-search",
    "arguments": {
        "query": "latest news on AI"
    }
}

出力例：

{
    "data": [
        {
            "title": "Example result",
            "link": "https://example.com/page",
            "snippet": "Short preview text."
        }
    ]
}

このツールは、その JSON を整形済みテキストとして返します：{ "content": [{ "type": "text", "text": "<json above>" }] }。

AI エージェント向けの AI 検索、X 検索、ウェブ検索に加え、ページ抽出、X データツール、People Search（X、YouTube、LinkedIn、TikTok で人やクリエイターを検索）が利用できます。Desearch API キーはご自身で用意してください。

ツール

Desearch MCP サーバーには、次のツールが含まれています。

search や fetch などの検索ツールでは、readOnlyHint: true、destructiveHint: false、openWorldHint: true が設定されています。people-search はユーザーの Desearch 残高に課金される有料ジョブを開始するため、readOnlyHint は false、destructiveHint は true です。people-search-control は検索をキャンセルできるため、readOnlyHint は false、destructiveHint は true です。すべてのツールで openWorldHint が true になっています。呼び出し時にライブの外部ソースへアクセスするためです。

• AI Search (ai-search)：関連リンクと要約付きで、X とウェブを AI 検索します。tools では短いソース ID（web、twitter、arxiv、wikipedia、hackernews、reddit）を使用します。Web Search、ArXiv Search、Wikipedia Search、Hacker News Search、Reddit Search などの古いラベルも引き続き受け付けられ、短い ID に変換されて送信されます。youtube は受け付けません。デフォルトは ["web", "twitter"] です。
• X Search (x-search)：X で投稿を検索します。引数：query（必須）、count（任意、デフォルトは 20）。並べ替えは「トップ」のままです。任意のフィルター：user、start_date、end_date（YYYY-MM-DD）、lang、verified、blue_verified、is_quote、is_video、is_image、min_retweets、min_replies、min_likes。
• Search (search)：{ results: [{ id, title, url }] } を返すウェブ検索です。引数：query（必須）。id は検索結果の URL です。
• Fetch Page (fetch)：公開ページをテキストとして読み取ります。引数：id（必須。search から取得した http または https の URL）。
• Web Search (web-search)：SERP 形式のウェブ検索です。引数：query（必須）、start（任意のページネーションオフセット）。
• Web Links Search (web-links-search)：ウェブリンク検索です。引数：prompt（必須）、tools（任意。web のみ。デフォルトは ["web"]。Web Search も受け付けられ、web に書き換えられます）、count（任意、10～200）。リンク／ウェブ API は他のソースを受け付けないため、列挙型には含まれていません。
• Extract (extract)：公開 URL をテキストまたは HTML として読み取ります。クロールよりこちらを推奨します。引数：url（必須）、format（任意。html または text）、js（任意）、wait（任意。ミリ秒）。
• Web Crawl (web-crawl)：レガシーの /web/crawl ルートで、extract と同じ引数を使用します。SDK では webCrawl は非推奨とされ、代わりに extract が推奨されています。このツールは、該当ルートに引き続きアクセスできるように残されています。新しい連携では extract を優先してください。
• X Links Search (x-links-search)：X の投稿リンクを AI 検索します。引数：prompt（必須）、count（任意、10～200）。
• X Posts By URLs (x-posts-by-urls)：URL のリストから投稿の全文を取得します。引数：urls（必須）。
• X Post By ID (x-post-by-id)：ID で指定した投稿を取得します。引数：id（必須）。
• X Posts By User (x-posts-by-user)：ユーザーの投稿を取得します。引数：user（必須）、query（任意）、count（任意、1～100）。
• X Post Retweeters (x-post-retweeters)：投稿をリポストしたユーザーを取得します。引数：id（必須）、cursor（任意）。
• X User Posts (x-user-posts)：ユーザーのタイムラインを取得します。引数：username（必須）、cursor（任意）。
• X User Replies (x-user-replies)：ユーザーの投稿と返信を取得します。引数：user（必須）、count（任意、1～100）、query（任意）。
• X Post Replies (x-post-replies)：投稿への返信を取得します。引数：post_id（必須）、count（任意、1～100）、query（任意）。
• X Trends (x-trends)：地域のトレンドトピックを取得します。引数：woeid（必須）、count（任意、30～100）。
• People Search (people-search)：ユーザーの Desearch 残高に課金される有料ジョブを開始します。平易な言葉で記述した条件に合う人を検索します。引数：platform（必須：x、youtube、linkedin、tiktok のいずれか）、query（必須、3～1000 文字）、count（任意、5～200、API のデフォルトは 25）、min_score（任意、0～100）、exclude（任意のハンドル）、metadata（任意のラベル。下記参照）、idempotency_key（任意）、および該当プラットフォームのフィルター（下記参照）。task_id、ステータス、reserved_cost_usd を返します。
• People Search Status (people-search-status)：タスクのステータス、進捗、コストに加え、これまでに見つかった人のページを取得します。引数：task_id（必須）、cursor（任意。前回の呼び出しで返された next_cursor）、limit（任意、1～100、デフォルトは 25）、include_people（任意、デフォルトは true）。無料です。
• Control People Search (people-search-control)：タスクを一時停止、再開、またはキャンセルします。引数：task_id（必須）、action（必須：pause、resume、cancel のいずれか）。無料です。
• List People Search Tasks (people-search-tasks)：新しいものから順に、検索の一覧を取得します。引数：platform（任意）、status（任意のリスト。例：["running", "paused"]）、limit（任意、1～100）、cursor（任意）、metadata（任意。タスクが持つ必要のある最大 3 つのラベル。例：{"campaign": "q4-outbound"}）。無料です。
• List People Found (people-profiles)：検索で見つかった全員を、プラットフォームごとに 1 人 1 件で、その人を見つけた検索とともに取得します。引数：platform（必須）、q（任意。名前、ハンドル、プロフィール、または所在地に含まれるテキスト）、sort（任意：score、recent、audience のいずれか）、limit（任意、1～200、デフォルトは 25）、cursor（任意）、およびフィルター：has（全員が持っている必要のあるチャネル：email、website、x、linkedin、instagram、youtube、tiktok）、min_audience、max_audience、min_score、location、verified。無料です。 SDK メソッド → エンドポイント → MCP ツールの完全な対応表は、docs/API_MCP_PARITY.md にあります。公開されている desearch-js 1.5 のメソッドはすべてツールです。latestTweets は SDK から削除されており（1.0.1 の GET /twitter/latest）、公開されていません。People Search は desearch-js 1.5 に含まれていません。そのツールは /desearch/people/* ルートを直接呼び出し、対応表にも記載されています。

People Search

People Search は、平易な言葉での説明に合致する X プロフィール、YouTube クリエイター、LinkedIn メンバー、または TikTok クリエイターを検索します。検索結果には、適合スコア、一致した理由を示す一文、オーディエンス（フォロワー、YouTube ではチャンネル登録者）、所在地、検索で見つかった公開連絡先とリンクが含まれます。

検索はバックグラウンドタスクとして実行されます。

1. people-search は、ユーザーの Desearch 残高に課金される有料ジョブを開始し、すぐに task_id を返します。課金される People Search の呼び出しはこれだけです。プラットフォームごとの 1 人あたりの料金で count 人分を確保します（reserved_cost_usd）。検索が終了すると、実際に見つかった人数分のみ課金されます（1 人でも見つかった場合は検索ごとの最低料金が適用され、誰も見つからなかった場合は無料です）。残りの確保額は返金されます。同じ idempotency_key を送信すると、2 回目の検索を開始したり、追加で支払ったりせずに呼び出しを再試行できます。
2. 検索には通常 1～5 分かかります。people-search-status は、ステータス、進行状況、費用、見つかった人物をその時点まで返します。検索の実行中にも人物が見つかります。next_cursor を cursor として渡すと、新たに見つかった人物のみを取得できます。done が true で、has_more が false になったら、見つかった人物はすべて取得済みです。
3. people-search-control で一時停止、再開、キャンセルできます。検索をキャンセルした場合、すでに返された人物分のみ課金されます。

検索終了後も、見つかった人物の情報は 30 日間読み取り可能です。people-profiles は、すべての検索を対象にプラットフォームごとに人物を一覧表示します。has: ["email"] などのフィルターも使えます。

検索フィルターはプラットフォームによって異なります。該当しないフィルターは、課金される呼び出しの前に拒否されます。

プラットフォーム	フィルター
x	min_followers、max_followers、verified_only、countries、keywords、exclude_keywords
youtube	min_subscribers、max_subscribers、countries、require_contact、keywords、exclude_keywords
linkedin	min_followers、max_followers、countries、keywords、exclude_keywords
tiktok	min_followers、max_followers、require_contact、keywords、exclude_keywords

require_contact を指定すると、公開メールアドレスがあるクリエイターのみが対象になります（TikTok の場合はプロフィールの自己紹介欄にあるもの）。keywords と exclude_keywords には、それぞれ最大 20 個の単語を指定できます。

metadata を使うと、たとえば {"campaign": "q4-outbound", "workspace_id": "ws_42"} のように、独自のキーで検索にラベルを付けられます。検索ごとに最大 10 個のキーを指定できます。キーは a-z、0-9、_、.、- の 1～40 文字で、値は最大 200 文字の文字列です。不正なラベルは課金される呼び出しの前に拒否されます。ラベルはタスクの metadata として返されます。また、metadata: {"campaign": "q4-outbound"} を指定した people-search-tasks は、該当するラベルが付いた検索のみを一覧表示します（最大 3 組、完全一致）。検索自体ではラベルは使用されません。

プロンプト：公開メールアドレスがある TikTok のスキンケアクリエイターを 10 人見つける。

{
    "name": "people-search",
    "arguments": {
        "platform": "tiktok",
        "query": "Skincare creators who review skincare products",
        "count": 10,
        "require_contact": true
    }
}

出力例：

{
    "task_id": "3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d",
    "platform": "tiktok",
    "status": "queued",
    "done": false,
    "query": "Skincare creators who review skincare products",
    "count": 10,
    "result_count": 0,
    "reserved_cost_usd": 0.5,
    "created_at": "2026-10-17T10:00:00Z",
    "cost_usd": 0.5,
    "currency": "USD",
    "next": "Searches usually take 1 to 5 minutes. Poll people-search-status with this task_id every 15 to 30 seconds; people appear while it runs."
}

続いて、people-search-status に {"task_id": "3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d"} を指定してポーリングします。

{
    "task_id": "3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d",
    "platform": "tiktok",
    "status": "running",
    "stage": "processing",
    "done": false,
    "query": "Skincare creators who review skincare products",
    "count": 10,
    "result_count": 4,
    "progress": { "round": 1, "candidates_processed": 40, "qualified": 4 },
    "reserved_cost_usd": 0.5,
    "created_at": "2026-10-17T10:00:00Z",
    "people": [
        {
            "id": "tiktok:example_creator",
            "platform": "tiktok",
            "handle": "example_creator",
            "name": "Example Creator",
            "url": "https://www.tiktok.com/@example_creator",
            "audience": 48200,
            "location": "United States",
            "score": 88,
            "why": "Reviews sunscreens and moisturizers every week.",
            "contacts": [{ "type": "email", "value": "[email protected]" }],
            "links": [{ "type": "instagram", "url": "https://instagram.com/example_creator" }],
            "evidence_url": "https://www.tiktok.com/@example_creator/video/1"
        }
    ],
    "next_cursor": "4",
    "has_more": false,
    "next": "Still searching. Wait 15 to 30 seconds, then call people-search-status again with cursor \"4\" to get only the people found since this call."
}

上記の出力は 1 人分に短縮されています。CSV と JSON Lines のダウンロード（/export ルート）は MCP ツールではありません。ファイルを取得するには API を直接呼び出してください。

検索が終了すると、タスクには終了理由と完了状況も記載され、各人物の情報には、本人のプロフィールで確認できる内容が示されます（0.3.2 以降）。

{
    "status": "completed",
    "done": true,
    "completion_reason": "cost_limit",
    "coverage_limited": true,
    "warnings": [
        { "code": "partial_enrichment", "platform": "linkedin", "attempted": 20, "failed": 7, "by_reason": { "not_found": 7 } }
    ],
    "people": [
        {
            "handle": "example_engineer",
            "score": 74,
            "fully_verified": false,
            "unverified_criteria": ["Profile fit: Software Engineer based in Georgia (unknown)"],
            "enrichment": "failed",
            "enrichment_error": "not_found"
        }
    ],
    "next": "Finished early: a budget stopped it (cost_limit) before it found 10 people, so more people may match. You have every person it found."
}

• completion_reason は count_reached、rounds_exhausted、no_candidates、zero_qualified、candidate_budget、cost_limit、time_limit、cancelled、または failed のいずれかです。検索の実行中は表示されません。
• coverage_limited は、予算の上限に達して count 人が見つかる前に検索が停止した場合にのみ（true として）表示されます。ステータスは引き続き completed です。
• warnings には、検索の信頼性を部分的に低下させた要因が記載されます。partial_enrichment は、検索後に attempted 件のプロフィールのうち failed 件を読み込めなかったことを示します。そのため、該当する人は検索結果に基づいてスコア付けされ、enrichment: "failed" と enrichment_error が表示されます。
• fully_verified は、すべての条件が本人のプロフィールまたは投稿で確認できた場合に true になります。unverified_criteria には、確認できなかった条件が最大5件まで記載されます。該当する内容は (unknown)、(not met)、または適用される除外条件 (applies) です。いずれも参考情報であり、その人は引き続き条件を満たしています。2026-10-20より前にスコア付けされた結果には、これらの項目はありません。

前提条件 📋

• Desearch API キー
• Node.js（v20.18.1以上。Node 22はサポートされています。Node 18はサポートされていません。）
• Claude Desktop がインストールされていること
• Cursor IDE

インストール 🛠️

NPMによるインストール

パッケージ名は desearch-mcp-server です。現在のバージョンは npm にあります。リリースノートについては CHANGELOG.md をご覧ください。stdio エントリは desearch-mcp-server bin（build/index.js）で、DESEARCH_API_KEY が必要です。

npm install -g desearch-mcp-server

または、グローバルインストールせずに実行できます。

npx -y desearch-mcp-server@latest

Cursor または Claude から、この bin を直接起動できます。

{
    "mcpServers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server@latest"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

command: "desearch-mcp-server"（args なし）は、上記のグローバルインストール後に使うエントリと同じです。

Gemini CLI

このリポジトリから拡張機能をインストールします。Gemini CLI で Desearch API キーを入力すると（機密設定として保存されます）、ホスト型サーバー https://mcp.desearch.ai/mcp に接続します。

gemini extensions install https://github.com/Desearch-ai/mcp-desearch

後からキーを変更するには、gemini extensions config desearch を実行します。Cline などの AI エージェントは、llms-install.md に従ってサーバーをセットアップできます。

Smithery の使用

Smithery を介して Claude Desktop 用の Desearch MCP サーバーを自動的にインストールするには、次のようにします。

npx -y @smithery/cli install desearch/desearch --client claude

Cursor IDE の場合は、次のようにします。

npx -y @smithery/cli install desearch/desearch --client cursor

Windsurf

Windsurf の Cascade エージェントは、mcp_config.json の mcpServers キーから MCP サーバーを読み込みます。Cascade パネルから ...（Actions）メニューをクリックし、Open MCP config file を選択して開きます。Windsurf のビルドでは ~/.codeium/windsurf/mcp_config.json が使用されます（Windows では %USERPROFILE%\.codeium\windsurf\mcp_config.json）。新しいビルドでは、代わりに ~/.config/devin/mcp_config.json が開く場合があります（Windows では %APPDATA%\devin\mcp_config.json）。この操作で開いたファイルを編集してください。

ホスト型サーバー（ローカルインストール不要）。リモートサーバーでは serverUrl と headers を使用します。

{
    "mcpServers": {
        "desearch": {
            "serverUrl": "https://mcp.desearch.ai/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

キーをファイルに記載しないようにするには、Windsurf で環境変数を展開できます。"Authorization": "Bearer ${env:DESEARCH_API_KEY}"

ローカル stdio を使用する方法：

{
    "mcpServers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server@latest"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

ファイルを保存し、Cascade の MCP サーバーリストを更新します。

Zed

Zed では MCP サーバーをコンテキストサーバーと呼びます。zed: open settings file アクションで設定ファイルを開き（または Settings → AI → MCP Servers → Add Server を使用し）、context_servers エントリを追加します。

ホスト型サーバー：

{
    "context_servers": {
        "desearch": {
            "url": "https://mcp.desearch.ai/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

ローカル stdio を使用する方法：

{
    "context_servers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server@latest"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

Settings → AI → MCP Servers で desearch の横にある点が緑色（「Server is active」）に変わると、サーバーの準備が完了です。

設定 ⚙️

1. Desearch MCP サーバーを実行するように Cursor IDE を設定する

Cursor IDE を開き、コマンドパレット Cmd+Shift+P または Ctrl+Shift+P にアクセスして、Open MCP Settings を検索します。Add new global MCP server をクリックして mcp.json ファイルを開きます。

2. Desearch サーバーの設定を追加する：

{
    "mcpServers": {
        "desearch": {
            "command": "desearch-mcp-server",
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

your-api-key を、console.desearch.ai/api-keys で取得した実際の Desearch API キーに置き換えます。

3. Cursor IDE を再起動する

変更を反映するには、次の操作を行います。

1. Cursor IDE を完全に終了します
2. Cursor IDE を再起動します

1. Desearch MCP サーバーを実行するように Claude Desktop を設定する

Claude Desktop アプリを開き、左上のメニューバーから Developer Mode を有効にします。

有効にしたら、左上のメニューバーから Settings を開き、Developer Option に移動します。そこにある Edit Config ボタンをクリックすると、claude_desktop_config.json ファイルが開き、必要な編集を行えます。

または、ターミナルから claude_desktop_config.json を開く場合

macOS の場合：

1. Claude Desktop の設定を開きます。

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows の場合：

1. Claude Desktop の設定ファイルを開きます。

code %APPDATA%\Claude\claude_desktop_config.json

2. Desearch サーバーの設定を追加する：

{
    "mcpServers": {
        "desearch": {
            "command": "desearch-mcp-server",
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

your-api-key を、console.desearch.ai/api-keys で取得した実際の Desearch API キーに置き換えます。

3. Claude Desktop を再起動する

変更を反映するには、次の操作を行います。

1. Claude Desktop を完全に終了します
2. Claude Desktop を再起動します
3. Settings > Developer > desearch でステータスを確認すると、サーバーの動作を検証できます

リモート Streamable HTTP

同じサーバーを MCP Streamable HTTP 経由でリモートクライアント向けに実行できます。ローカルの stdio（desearch-mcp-server、Smithery）には変更がなく、引き続き環境変数から DESEARCH_API_KEY を読み込みます。

リモートリクエストでは、この環境変数は使用されません。検出にキーは不要です。initialize、notifications/initialized、ping、tools/list、prompts/list、resources/list、resources/templates/list は 200 を返すため、マーケットプレイスのスキャナーがツール一覧を読み取れます。tools/call とその他すべてのメソッドには、呼び出し元自身の Desearch API キー（console.desearch.ai/api-keys で取得するものと同じキー）が引き続き必要です。

• Authorization: Bearer <DESEARCH_API_KEY>（推奨）
• x-api-key: <DESEARCH_API_KEY>（こちらも使用できます）
• 以下の OAuth サインイン後の Authorization: Bearer <oauth access token>

Authorization: <DESEARCH_API_KEY> のみの値も使用できます。クエリ文字列からキーが読み込まれることはありません。サーバー共有シークレットはありません。有効なキーまたはアクセストークンなしで保護された呼び出しを行うと、/.well-known/oauth-protected-resource/mcp を示す WWW-Authenticate ヘッダーとともに 401 が返されます。ホストされたプロセスは、呼び出しに必要な場合に限り、リクエストごとの Desearch API キーを Desearch API に転送します。OAuth アクセストークンは不透明です。サーバーはそのトークンに保存されたキーを検索し、生のキーをトークンに含めません。

MCP エンドポイントは POST /mcp です。レスポンスは JSON です（ステートレスな Streamable HTTP）。サーバーはセッションを保持せず、サーバーからクライアントへのメッセージもプッシュしないため、/mcp への GET と DELETE は 405 を返します。GET /、GET /health、GET /api/health は、認証不要のヘルスチェックです。

ホストされたエンドポイント

公開 Streamable HTTP エンドポイントは https://mcp.desearch.ai/mcp です。ツール一覧の取得にキーは不要です。各 tools/call リクエストで、Authorization: Bearer <DESEARCH_API_KEY> を使用して Desearch API キーを送信してください（推奨）。x-api-key ヘッダーも使用できます。console.desearch.ai/api-keys で取得したキーを使用してください。サーバーはクエリ文字列からキーを読み込みません。リモートリクエストでは、プロセスレベルの DESEARCH_API_KEY は使用されません。

Cursor など、あらゆるリモート MCP クライアント：

{
    "mcpServers": {
        "desearch": {
            "url": "https://mcp.desearch.ai/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

OAuth サインイン

MCP 認証仕様（2025-06-18）に準拠するクライアントは、リクエストごとにキーを送信する代わりにサインインできます。検出用ドキュメントは次のとおりです。

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-protected-resource/mcp
• GET /.well-known/oauth-authorization-server
• GET /.well-known/openid-configuration（同じ認可サーバーのドキュメント）

POST /register は動的クライアント登録です。GET /authorize は、ユーザーが API キーを貼り付ける Desearch のページです。POST /token は認可コードを交換し、リフレッシュトークンをローテーションします。PKCE S256 が必須です。パブリッククライアントは token_endpoint_auth_method に none を使用します。

許可されるコールバック URL：

• https://claude.ai/api/mcp/auth_callback
• https://claude.com/api/mcp/auth_callback
• https://chatgpt.com/connector_platform_oauth_redirect
• https://chatgpt.com/connector/oauth/{callback_id}
• 任意のポートでのループバック http://localhost、http://127.0.0.1、http://[::1]（ホストとパスは登録済みのコールバックと一致している必要があります）

コネクター URL は https://mcp.desearch.ai/mcp です。サインインページで、console.desearch.ai/api-keys のキーを貼り付けます。クライアントが自身を登録できる場合は、クライアント ID を空欄にします。

ホストの環境変数：

変数	必須	用途
OAUTH_ISSUER	本番環境	末尾にスラッシュを付けない正規オリジンです。例：https://mcp.desearch.ai。NODE_ENV=production または VERCEL が設定されている場合は必須です。設定されていない場合、プロセスは OAuth とベアラーチャレンジを拒否します。Issuer が X-Forwarded-Host から取得されることはありません。ローカルではリクエスト URL が使用されます。
OAUTH_RESOURCE	いいえ	正規 MCP URL です。デフォルトは {OAUTH_ISSUER}/mcp です。保存された Audience がこのリソースと一致しない場合、アクセストークンは拒否されます。
OAUTH_STORE	本番環境	memory（ローカルのデフォルト）または redis です。本番環境（NODE_ENV=production または VERCEL）では、redis でない限り起動が拒否されます。
REDIS_URL	OAUTH_STORE=redis の場合	Redis 接続文字列（redis:// または rediss://）です。
OAUTH_ENCRYPTION_KEY	OAUTH_STORE=redis の場合	32 バイトのキー（base64 または hex）です。openssl rand -base64 32 で生成します。保存された API キーを暗号化します。
OAUTH_ACCESS_TTL_SEC	いいえ	アクセストークンの有効期間です。デフォルトは 3600 です。範囲は 60～86400 です。
OAUTH_REFRESH_TTL_SEC	いいえ	リフレッシュトークンの有効期間です。デフォルトは 30 日です。範囲は 300 秒～90 日です。
OAUTH_CODE_TTL_SEC	いいえ	認可コードの有効期間です。デフォルトは 300 です。範囲は 30～600 です。
OAUTH_CLIENT_TTL_SEC	いいえ	動的クライアントの有効期間です。デフォルトは 90 日です。範囲は 3600 秒～5 年です。
OAUTH_REGISTER_RATE_LIMIT	いいえ	IP ごとのウィンドウ内の登録試行回数です。デフォルトは 10 です。範囲は 1～10000 です。
OAUTH_REGISTER_RATE_WINDOW_SEC	いいえ	登録のレート制限ウィンドウの秒数です。デフォルトは 3600（1 時間）です。範囲は 1～86400 です。
OAUTH_AUTHORIZE_RATE_LIMIT	いいえ	IP ごとのウィンドウ内のサインインキー確認回数です。デフォルトは 20 です。範囲は 1～10000 です。
OAUTH_AUTHORIZE_RATE_WINDOW_SEC	いいえ	サインインキー確認のウィンドウの秒数です。デフォルトは 600（10 分）です。範囲は 1～86400 です。
DESEARCH_API_BASE	いいえ	キー確認に使用するホストです。デフォルトは https://api.desearch.ai です。
OAUTH_REQUIRE_AUTH_ON_INITIALIZE	いいえ	true に設定すると、initialize でキーまたはアクセストークンが必須になります。デフォルトでは無効のため、キーなしの initialize は引き続き公開されます。tools/list はいずれの場合も公開されます。

キー確認では GET /twitter/trends?woeid=1&count=1 が呼び出されます。有効なキーは認証された後、無効な入力として拒否されます（HTTP 422）。そのため、確認のためにトレンドの全クエリが実行されることはありません。422 のみが有効なキーとして扱われます。401 と 403 はキーを拒否します。2xx を含むその他のステータスはすべて検証エラーとなり、有効とは扱われません。

POST /register は、IP ごとに 1 時間あたり 10 件のリクエストを許可します。サインインキーの確認では、IP ごとに 10 分あたり 20 件のリクエストが許可されます。上限を超えたリクエストは Retry-After とともに 429 を返します。Vercel では、アドレスとして X-Forwarded-For の最初のホップが使用されます。サインインページでは Referrer-Policy: same-origin が設定され、ほかの認可フィールドとともに response_type=code が送信されます。フォームは同一オリジンの Origin または Referer を受け付けます。また、Origin がない場合、または null の場合は、Sec-Fetch-Site: same-origin を受け付けます。Sec-Fetch-Site が cross-site または same-site の場合、外部の Origin の場合、およびオリジンを示す情報がない POST は拒否されます。

Claude で使用する（カスタムコネクター）

Desearch はまだ Claude Connectors Directory に登録されていません。Desearch API キーを使用するか、OAuth でサインインして、ホスト型サーバーをカスタムコネクターとして追加できます。

参照先：カスタムリモート MCP コネクター と コネクター認証。リクエストヘッダー認証は Claude のベータ機能です。

Claude.ai / Claude Desktop（組織の管理者）

1. Organization settings > Connectors を開きます。
2. Add を選択し、次に Custom を選択します。コネクターの種類を尋ねられたら、Web を選択します。
3. サーバー URL：https://mcp.desearch.ai/mcp
4. サインイン方法：No sign-in。
5. Request headers で、Authorization を追加し、値に Bearer <DESEARCH_API_KEY> を設定します。<DESEARCH_API_KEY> は Desearch API キーに置き換えてください。
6. Add を選択します。

ヘッダーの値は一度保存され、コネクターを使用する組織内の全員で共有されます。

OAuth を使用する場合：リクエストヘッダーの代わりにサインインを選択し、クライアントが自身を登録できるよう OAuth クライアント ID は空欄のままにして、Desearch のページに Desearch API キーを貼り付けます。ホスト型 Claude アプリのコールバック URL は https://claude.ai/api/mcp/auth_callback です。Claude Code はループバックコールバックを使用し、このサーバーは任意のポートで受け付けます。

Claude Code

claude mcp add --transport http desearch https://mcp.desearch.ai/mcp \
  --header "Authorization: Bearer your-api-key"

ローカルで実行する

npm install
npm run build
npm run start:http

これは 0.0.0.0:3000 でリッスンします（PORT と HOST で上書きできます）。MCP_TRANSPORT=http は --http と同じです。

curl -sS http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer your-api-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}'

Cursor（または任意のリモート MCP クライアント）：

{
    "mcpServers": {
        "desearch": {
            "url": "http://127.0.0.1:3000/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

イメージのデフォルトは stdio MCP（node build/index.js）です。Glama などのレジストリはコンテナを起動し、stdin/stdout で MCP 通信を行うため、上書きしない限りイメージに --http は渡しません。stdio では DESEARCH_API_KEY が必要です。Smithery はこのイメージのコマンドを使用しません。smithery.yaml が node build/index.js を起動し、DESEARCH_API_KEY を自動的に注入します。

Streamable HTTP は上書き設定です。コマンドを --http に置き換えるか、MCP_TRANSPORT=http を設定してデフォルトのコマンドをそのまま使用してください。このモードでもイメージはポート 3000 を公開します。

docker build -t desearch-mcp .
# stdio (image default)
docker run --rm -e DESEARCH_API_KEY=your-api-key -i desearch-mcp
# Streamable HTTP
docker run --rm -p 3000:3000 desearch-mcp node build/index.js --http
# same HTTP mode via env, without replacing the command
docker run --rm -e MCP_TRANSPORT=http -p 3000:3000 desearch-mcp

Vercel にデプロイする

JSON-RPC の呼び出しごとに応答が 1 つ返るため、MCP ハンドラーには Vercel が適しています。vercel.json はプロジェクトをビルドし、POST /mcp を提供して、関数の実行時間を 60 秒に設定します。同じファイルで、公開 OAuth パスを /api/* に書き換えます。サーバーは書き換え後のパスと公開パスの両方を受け付け、メタデータ文書には引き続き公開パスが記載されます。Hobby プランでは関数の実行時間にこれより短い上限があるため、AI Search ツールの呼び出しには少なくとも 60 秒を許可するプランが必要です。initialize と tools/list はどちらの設定でも短時間で完了します。

OAuth コードとトークンには共有ストレージが必要です。Vercel では OAUTH_STORE=redis、REDIS_URL、OAUTH_ENCRYPTION_KEY、OAUTH_ISSUER=https://mcp.desearch.ai を設定してください。Vercel はすべての関数に VERCEL を設定するため、OAUTH_ISSUER が未設定、または OAUTH_STORE が redis 以外の場合、サーバーは OAuth を拒否します。OAUTH_REQUIRE_AUTH_ON_INITIALIZE=true は任意です。クライアントが公開 initialize を理由にサインインを省略する場合を除き、未設定のままにしてください。

Vercel プロジェクトにサーバー側の Desearch API キーは必要ありません。デプロイ後のエンドポイントは次のとおりです。

https://<project>.vercel.app/mcp

https://mcp.desearch.ai/mcp は公開ホスト名です。このリポジトリでは DNS レコードを作成しません。クライアントは Authorization: Bearer <DESEARCH_API_KEY> を送信します（推奨）。x-api-key ヘッダーも受け付けます。

Vercel の代わりに長時間稼働する Node ホストで実行する場合は、同じ node build/index.js --http プロセスをフォールバックとして使用できます。Docker イメージのデフォルトは stdio です。イメージから Streamable HTTP を提供するには、--http を渡すか、MCP_TRANSPORT=http を設定してください。

トラブルシューティング 🔧

よくある問題

1. サーバーが見つからない

   • Claude または Cursor Desktop の設定構文を確認してください
   • Node.js がインストールされていることを確認してください

2. API キーの問題

   • DESEARCH_API_KEY が有効であることを確認してください
   • DESEARCH_API_KEY が Cursor または Claude Desktop の設定に正しく設定されていることを確認してください
   • API キーの前後にスペースがないことを確認してください
   • リモート HTTP サーバーには、Authorization: Bearer <DESEARCH_API_KEY>（推奨）を送信してください。x-api-key も使用できます。ホストされている DESEARCH_API_KEY 環境変数は、これらのリクエストには使用されません。

3. 接続の問題

   • Claude Desktop または Cursor IDE を完全に再起動してください
   • Claude Desktop のログを確認してください。

   # macOS
   tail -n 50 -f ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   type "%APPDATA%\Claude\logs\mcp*.log"