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

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

Tavily公式のMCPサーバーをClaude Codeにclaude mcp addで接続する手順です。キーなし・APIキー・OAuth・ローカルnpx起動の4通りの設定と、使うキーの決まり方を扱います。

読了目安 約15分

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認証に分かれます。ここではclaude mcp addを使った具体的なコマンドと、それぞれの選び方をまとめます。

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

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

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

Cursorをはじめ他のMCPクライアントとも互換性があります。ただしキーなしの接続で呼べるのはtavily-searchとtavily-extractの2つで、tavily-mapとtavily-crawlにはAPIキーが要ります(詳しくは接続手順の節)。

接続方式は4通り、キーの扱いで選ぶ

Tavilyは公式にリモートMCPサーバー(https://mcp.tavily.com/mcp/)を提供しており、ローカルへのインストールなしに使い始められます。リモートはAPIキーなしの利用も含めて3通りに分かれ、ローカルのnpx起動を足すと4通りです。

くらべる

リモート接続のキーの渡し方

試すだけ

キーなし

アカウントもAPIキーも要りません。X-Tavily-Access-Mode: keylessヘッダーを付けるだけで、無料のまま検索と抽出を使えます。レート制限があります。

すぐ使う

APIキー

URLの?tavilyApiKey=か、Authorizationヘッダーにキーを載せます。1コマンドで終わり、制限は自分のアカウントの枠に従います。

キーを残さない

OAuth

URLにキーを含めず、ブラウザでTavilyにサインインして認可します。どのキーが課金されるかはダッシュボードのキー名で決まります。

ローカル(npx)は、Node.js v20以上が必要で、DEFAULT_PARAMETERSなどを環境変数で細かく制御したい場合に向く方式です。個人利用ならリモートで足ります。

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での都度ダウンロードを避けたい、あるいはソースを手元で確認してから動かしたい場合に向いています。

キーなしで試す

アカウントなしで動かしたいときは、キーを渡さずにkeylessヘッダーを付けます。

claude mcp add tavily-remote-mcp --transport http https://mcp.tavily.com/mcp/ \
  --header "X-Tavily-Access-Mode: keyless"

ヘッダーが無いと、サーバーはクライアントにサインインを求めます。URLしか受け付けないクライアントはヘッダーを送れないため、キーなしは使えません。対応エンドポイントは/searchと/extractの2つで、/map・/crawl・/researchにはAPIキーが必要です。

レート制限に達したときは、Tavilyが次に何をすればよいかを自然文でエージェントに返します。無料のAPIキー(月1,000クレジット、クレジットカード不要)を取得して差し替えれば、同じ使い方のまま上限が変わります。keylessヘッダーと有効なAuthorization: Bearerヘッダーを両方送った場合は、APIキーが優先されます。

APIキーをURLでなくヘッダーで渡す

claude mcp addには--header(短縮形-H)があり、HTTP接続のキーをヘッダーに載せられます。v2.1.287のclaude mcp add --helpでは、HTTPサーバー向けの例として次の形が示されています。

claude mcp add --transport http corridor https://app.corridor.dev/api/mcp \
  --header "Authorization: Bearer ..."

Tavilyの場合は、同じ形でURLをキーなしのhttps://mcp.tavily.com/mcp/にし、ヘッダーにTavilyのAPIキーを渡します。この形ならMCPサーバーのURL自体にはキーが含まれません。

claude mcp add --transport http tavily https://mcp.tavily.com/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

同じ--helpには、OAuthの事前登録クライアント向けに--client-id、--client-secret、--callback-portも並んでいます。Tavilyの標準のOAuthは追加の設定なしで動くため、これらは使いません。

--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キーが認証に使われるかを決められます。

手順

OAuthで使われるキーの決まり方

  1. 1

    mcp_auth_defaultという名前のキーを探す

    個人アカウントとチームの両方にあれば、個人のキーが優先されます。どちらか片方だけなら、そのキーが使われます。

  2. 2

    無ければ個人アカウントのdefaultキー

    mcp_auth_defaultがどこにも無いときの次の候補です。

  3. 3

    それも無ければ最初に見つかったキー

    defaultキーも設定されていない場合の最後の候補です。

複数のAPIキーを使い分けているチームで「OAuthでログインしたのに想定外のキーが課金されている」ときは、この優先順位を確認すると原因が絞れます。保存済みのOAuth資格情報を消して認証し直したいときは、Claude Codeの/mcpでサーバーのメニューを開き、Clear authenticationを選びます。なおnpx mcp-remote経由でOAuth接続している場合は、認証情報の保存先は~/.mcp-authです。

実際の使い方

接続後は、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\"}"
      }
    }
  }
}

チームで共有するサーバーでは、利用者ごとの識別も設定できます。ローカルは環境変数、リモートはX-Human-Idヘッダー(URLのhumanIdクエリパラメータでも可)で、利用者ごとの分析にTavily側が活用します。環境変数名はGitHubのREADMEではTAVILY_HUMAN_ID、TavilyのドキュメントページではHUMAN_IDと書かれています。値は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と表示されることがあります。Claude Code v2.1.221以降で、既定ではオフのキャッシュが、段階展開で有効になった場合とMCP_DISCOVERY_CACHE=1を指定した場合に使われているためです。初回のツール呼び出し時に接続されるので、利用者側の操作は要りません。詳細はMCP_DISCOVERY_CACHEとはにまとめています。

よくあるつまずき

APIキーの書式エラー。TavilyのAPIキーはtvly-から始まる書式です。書式が違うと認証に失敗することがあります。Tavily Playgroundでキーの有効性を単体テストできます。

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>で削除します。

まとめ

個人利用なら、APIキー付きのURLをclaude mcp addに渡す1コマンドで導入は完結します。tavily-mapとtavily-crawlまで使うならキー付きの接続が必要で、キーなしの接続で呼べるのはtavily-searchとtavily-extractの2つです。自前のMCPサーバーを構築してTavily以外のデータソースも扱いたくなった場合は、MCPサーバー自作ガイドを参照してください。

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

関連する記事

Claude Code をもっと見る →