Claude Media
TavilyのMCPサーバーをClaude Codeに接続する手順
Claude CodeMCPClaude連携チュートリアル

TavilyのMCPサーバーをClaude Codeに接続する手順

Tavily公式のMCPサーバーをClaude Codeにclaude mcp addで接続する手順です。APIキー方式・OAuth方式・ローカルnpx起動の3通りの設定を公式ドキュメントに基づいて扱います。

読了目安 約11分

Tavily MCP Serverは、検索API企業Tavilyが公式に配布するMCP(Model Context Protocol)サーバーです。tavily-search・tavily-extract・tavily-map・tavily-crawlの4ツールをClaude Codeに公開し、エージェントがセッション内からリアルタイムのWeb検索やページ抽出を呼び出せるようになります。

接続方法はリモートMCPサーバーへのHTTP接続とローカルでのnpx起動の2系統があり、リモート接続はさらにAPIキーをURLに含める方式とOAuth認証の2通りに分かれます。ここではclaude mcp addを使った具体的なコマンドと、それぞれの選び方をまとめます。

Tavily MCPサーバーが公開する4つのツール

Tavily MCP Serverが提供するツールは、検索・抽出・マップ・クロールの4つです。

ツールできること
tavily-searchできることリアルタイムのWeb検索。ニュース検索やドメイン指定検索にも対応
tavily-extractできること指定したURLからページ本文を抽出
tavily-mapできることサイト構造を構造化したマップとして生成
tavily-crawlできることサイトを体系的に巡回してページ群を収集

Cursorをはじめ他のMCPクライアントとも互換性があり、READMEの謝辞にはAnthropicとClaude Desktopへの言及があります。

リモート接続とローカル接続、どちらを選ぶか

Tavilyは公式にリモートMCPサーバー(https://mcp.tavily.com/mcp/)を提供しており、ローカルへのインストールなしに使い始められます。それぞれの選び方は用途によって変わります。

方式向いている場面必要なもの
リモート(APIキー方式)向いている場面すぐに試したい、設定を1コマンドで終えたい必要なものTavily APIキーのみ
リモート(OAuth方式)向いている場面APIキーをURLや設定ファイルに残したくない必要なものブラウザでのログイン
ローカル(npx)向いている場面オフライン検証、環境変数を細かく制御したい必要なものNode.js v20以上

個人利用であればリモート接続で十分です。APIキーをコマンド履歴や.mcp.jsonに残したくない場合はOAuth方式を選びます。

Claude Codeへの接続手順(claude mcp add)

まずAPIキーをURLに含める方式です。Tavilyのダッシュボードで取得したAPIキーをそのまま渡します。

claude mcp add --transport http tavily \
  https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

APIキーを設定に残したくない場合は、キーを省略してOAuth方式で追加します。

claude mcp add --transport http tavily https://mcp.tavily.com/mcp

OAuth方式で追加した直後はまだ認証が済んでいません。Claude Code内で/mcpを実行してTavilyサーバーを選び、ブラウザでの認証フローを完了させます。セッションを起動せずに認証だけ済ませたい場合は、シェルから直接claude mcp login tavilyを実行しても同じ認証フローが開始できます。

ローカルでサーバーを起動する場合は、--transport stdioとAPIキーの環境変数を渡し、--より後ろにサーバー起動コマンドを続けます。

claude mcp add --env TAVILY_API_KEY=<your-api-key> --transport stdio tavily \
  -- npx -y tavily-mcp@latest

なお公式ドキュメント内でもnpxのバージョン指定は@latest・@0.1.3・@0.1.2と資料によってばらつきがあります。特定バージョンへの固定が必要な事情がなければ@latestを使い、チーム共有など再現性が必要な場面だけバージョンを固定する運用が安全です。

npxの代わりにソースからビルドする方法も公式に用意されています。git clone https://github.com/tavily-ai/tavily-mcp.gitでリポジトリを取得し、npm installとnpm run buildを実行するとローカルにビルド済みのサーバーができます。この方法はGitがインストールされている環境限定で、macOSはbrew install git、Debian/Ubuntu系はsudo apt install gitで用意できます。npxでの都度ダウンロードを避けたい、あるいはソースを手元で確認してから動かしたい場合に向いています。

--scope userを付けると、追加したTavilyサーバーが全プロジェクトで使えるようになります。プロジェクトごとの追加(既定のlocalスコープ)や.mcp.jsonによるチーム共有など、スコープの仕組み自体はTavily固有ではなくClaude Code共通の機能です。詳しい使い分けはClaude Code MCP設定ガイドにまとめています。

接続できたかを確認する

claude mcp addはコマンドが成功するとAdded ...という行を表示しますが、これは設定が書き込まれたことを示すだけで、実際にTavilyサーバーへ接続できたかは別です。接続状態は次のコマンドで確認します。

claude mcp list
claude mcp get tavily

claude mcp listはサーバーごとに✔ Connected・! Needs authentication・✘ Failed to connectのいずれかを表示します。OAuth方式で追加した直後は! Needs authenticationのままなので、/mcpから認証を完了させるまではこの表示が正常です。✘ Failed to connectが出る場合は、APIキーの書式やネットワーク到達性を先に疑います。

OAuth認証時にどのAPIキーが使われるか

OAuth方式でサインインすると、Tavily側のダッシュボードでどのAPIキーを認証に使うかを名前で選べます。優先順位は次のとおりです。

  1. 個人アカウントにmcp_auth_defaultという名前のキーがあれば、それが使われる
  2. 所属チームにmcp_auth_defaultという名前のキーがあれば、それが使われる
  3. 個人・チーム双方にmcp_auth_defaultがある場合は、個人のキーが優先される
  4. どちらにもmcp_auth_defaultが無い場合は、個人アカウントのdefaultキーが使われ、それも無ければ最初に見つかったキーが使われる

複数のAPIキーを使い分けているチームで「OAuthでログインしたのに想定外のキーが課金されている」ときは、この優先順位を確認すると原因が絞れます。

実際の使い方

接続後は、Claude Codeへの自然文の指示がそのままツール呼び出しに変換されます。公式ドキュメントが挙げる例は次のようなものです。

  • 一般的なWeb検索: 「量子コンピューティングの最近の進展を検索して」
  • ニュース検索: 「過去7日間のAIスタートアップに関するニュース記事を検索して」
  • ドメイン指定検索: 「nature.comとsciencedirect.comで気候変動の研究を検索して」
  • ページ抽出: 「このページから本文を抽出して: https://example.com/article」

検索と抽出を組み合わせ、「過去7日間のAIスタートアップのニュースを検索し、各記事の本文を抽出してレポートにまとめて」のように、複数ツールをまたぐ指示も1回のプロンプトで成立します。

デフォルトパラメータとユーザー識別(オプション)

毎回のツール呼び出しで同じパラメータを指定する代わりに、DEFAULT_PARAMETERSでデフォルト値をまとめて設定できます。リモート接続ではヘッダーとして、ローカル接続では環境変数として渡します。

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here",
        "DEFAULT_PARAMETERS": "{\"include_images\": true, \"max_results\": 15, \"search_depth\": \"advanced\"}"
      }
    }
  }
}

チームで共有するサーバーでは、利用者ごとの識別も設定できます。ローカルはTAVILY_HUMAN_ID環境変数、リモートはX-Human-Idヘッダーで、利用者ごとの分析にTavily側が活用します。値はTavily側でSHA-256によりハッシュ化されてから保存されるため、メールアドレスのような生のPIIよりも内部的な識別子を使うことが推奨されています。設定は任意で、指定しなくても動作は変わりません。

利用者を明示しなくても、セッション単位の識別子は自動で付きます。ローカル接続ではX-Session-IdがMCPサーバーのプロセスごとに1回生成され、そのプロセス内のツール呼び出し全体で共有されます。リモート接続では、MCPのinitializeハンドシェイクで返るmcp-session-idがそのまま同じ値として使われ、同一セッション内の複数のツール呼び出しをTavily側で紐づけられるようになっています。

出力が大きくなったときの挙動

tavily-crawlやsearch_depth: "advanced"を指定したtavily-searchは、返す情報量が多くなりがちです。Claude Code側にはMCPツールの出力サイズを制御する仕組みがあり、既定では25,000トークンを超えるとファイルに保存され、会話にはファイルパスへの参照だけが残ります。10,000トークンを超えた時点で警告も表示されます。この上限はMAX_MCP_OUTPUT_TOKENS環境変数で引き上げられ、クロール結果を毎回そのまま会話に読み込ませたい場合はこの値を大きくします。この仕組みはTavily固有ではなくClaude CodeがMCPツール全般に適用する共通の挙動です。

リモート接続を追加した直後、/mcpパネルの状態表示がcachedのままになることがあります。これはMCP_DISCOVERY_CACHEという環境変数が関わる挙動で、詳細はMCP_DISCOVERY_CACHEとはにまとめています。

よくあるつまずき

APIキーの書式エラー。TavilyのAPIキーはtvly-から始まる書式です。プレフィックスを含めずに貼り付けると、接続はできても検索リクエストが失敗します。Tavily Playgroundでキーの有効性を単体テストできます。

npxが古いバージョンを使い続ける。npxは一度取得した実行ファイルをキャッシュすることがあり、which npxでパスを確認し、必要なら設定側でフルパスを指定すると解決します。node・npmのバージョン確認(node --version / npm --version)も基本のチェック項目です。

サーバーが見つからない・繋がらない。ここまでの原因を潰しても解決しない場合は、MCPサーバー全般に共通する切り分け手順が有効です。設定ファイル・プロセス起動・認証・ツール表示の4層に分けて原因を絞る方法をMCPサーバーに接続できないときの切り分け手順で扱っています。

同じ名前で複数スコープに登録してしまう。local・project・userの各スコープに同じサーバー名を異なるエンドポイントで定義すると、claude mcp listと/mcpの両方で競合の警告が出ます。OAuthの認証情報もエンドポイントごとに個別管理されるため、スコープを整理した後は残したいエンドポイント以外をclaude mcp remove tavily --scope <scope>で削除します。

まとめ

Tavily MCP Serverの導入は、個人利用ならAPIキー付きのURLをclaude mcp addに渡す1コマンドで完結します。APIキーを設定に残したくない場合はOAuth方式、オフライン検証や細かい環境変数制御が必要な場合はローカルのnpx起動を選びます。tavily-search・tavily-extract・tavily-map・tavily-crawlの4ツールがそのまま使えるようになるため、追加のツール定義作業は不要です。自前のMCPサーバーを構築してTavily以外のデータソースも扱いたくなった場合は、MCPサーバー自作ガイドを参照してください。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →