Context7のMCPをClaude Codeに設定する手順とAPIキーの要否

Claude CodeにContext7を入れる最短手順は、ターミナルでnpx ctx7 setup --claudeを実行することです。手動ならclaude mcp addでMCPのURLhttps://mcp.context7.com/mcpを登録します。APIキーは必須ではありませんが、キーなしだとレート制限が低くなります。

# 自動設定(OAuthでAPIキーも発行される)
npx ctx7 setup --claude
 
# 手動設定(APIキーをヘッダーで渡す)
claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp

各手順の詳細は、以降の節で順に説明します。

Context7 MCPとは

Context7は、ライブラリやフレームワークの最新ドキュメントをAIコーディングエージェントのプロンプトに直接注入するMCPサーバーです。Upstashが開発しています。GitHub・GitLab・Bitbucketのリポジトリやウェブサイト、OpenAPI仕様、llms.txtファイルなどから情報を集め、バージョン指定つきのコード例として返します。MCPを使わず、llms.txtのページを手元に保存する方法はllms.txtのドキュメントをClaude Codeに取り込む手順で扱っています。

LLMの学習データは特定の時点で固定されるため、ライブラリのバージョンが上がるたびに古いAPIやパラメータ名で回答してしまう問題が起こります。Context7はこの問題に対し、プロンプトの実行時にドキュメントを取得して差し込むことで対応します。Claude Codeでの利用方法は3種類です。ctx7 CLIで自動設定する方法、claude mcp addでMCPサーバーとして手動登録する方法、プラグインで入れる方法があります。Material UI専用の公式ドキュメントMCPなら、MUI MCPの設定手順があります。

接続経路は3つ — 自分の環境ならどれか

Claude CodeからContext7へ届く道は、ctx7 setup・claude mcp add・プラグインの3本です。どれも最終的に同じresolve-library-idとquery-docs(またはctx7コマンド)でドキュメントを取りに行きます。違いは、誰が設定を書くか、Node.jsが要るか、APIキーをどう渡すかです。

ターミナルから最短で終えるならctx7 setup、.mcp.jsonの中身を手元で管理したいならclaude mcp add、ローカルにNode.jsを置きたくない環境ならプラグインが候補です。

MCPツールの中身 — resolve-library-idとquery-docs

Context7 MCPサーバーが公開するツールは2つです。resolve-library-idはライブラリ名からContext7用のIDを解決するツールで、検索対象のlibraryNameと、関連度でランク付けするためのquery(質問文)を受け取ります。query-docsは解決済みのIDに対してドキュメントを取得するツールで、/org/project形式の正確なlibraryIdと、取得したい内容を表すqueryを受け取ります。

通常はまずresolve-library-idでライブラリのIDを解決し、続けてquery-docsでドキュメントを取得する2段階です。IDをプロンプトに直接書けば、1段目のライブラリ照合を省けます。

ctx7 CLIでワンコマンド設定する

ctx7はContext7公式のCLIで、ドキュメント取得とエージェント設定の両方を担います。Node.js 22.13以上が前提です。

# インストールなしで実行し、対話式でモードとエージェントを選ぶ
npx ctx7 setup
 
# Claude Codeを指定して一発設定する場合
npx ctx7 setup --claude

ctx7 setupは初回実行時にMCPサーバーモードとCLI + Skillsモードのどちらを使うか尋ねます。モードを固定したい場合は--mcpまたは--cliを付けます。

# MCPサーバーモードで固定
npx ctx7 setup --mcp --claude
 
# CLI + Skillsモードで固定(~/.claude/skillsにdocsスキルを配置)
npx ctx7 setup --cli --claude
 
# プロジェクト単位の設定(既定はグローバル設定)
npx ctx7 setup --claude --project

設定はOAuthデバイスフローで進みます。ブラウザで開く検証用リンクと短いコードが表示され、別のデバイスでも認証を完了できるため、リモートやヘッドレス環境でも同じ手順が使えます。既にAPIキーを持っている場合は--api-keyで明示的に渡せます。

# 既存のAPIキーを使って非対話で設定
npx ctx7 setup --claude --api-key YOUR_API_KEY --yes

MCPサーバーモードで書き込まれるのは、MCPサーバーの登録先(.mcp.json)、エージェントのルール用ディレクトリに置かれるルールファイル、context7-mcpという名前のSkillの3種類です。CLI + Skillsモードではdocsスキルだけが置かれます。ctx7 setupを通したあとは、ライブラリの質問に反応するSkillが自動で働くため、プロンプトに「use context7」と書かなくても使えます。設定を取り消すにはnpx ctx7 remove --claudeを実行します。

claude mcp addで手動設定する

CLIの自動設定を使わず、claude mcp addで直接構成することもできます。ローカルでMCPサーバープロセスを起動するstdio方式と、Context7がホストするサーバーに接続するリモート方式の2通りです。

ローカルstdio方式(APIキーはコマンド引数で渡す):

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

リモートHTTP方式(APIキーはヘッダーで渡す):

claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp

スコープは--scopeで選びます。指定しなかったときの既定はlocal(このプロジェクトのみ・自分だけ)です。全プロジェクト共通にしたいときはuser、チームで.mcp.jsonを共有したいときはprojectを付けます。claude mcp addの構文全体、スコープの使い分け、OAuth認証の詳細はClaude Code MCP設定ガイドにまとめています。

設定ファイルに何が書かれるか(v2.1.287で確認)

作業用の空ディレクトリで--scope projectを付けて実行します(ユーザー設定には触れません)。リモートHTTP方式の結果は次のとおりです。

$ claude mcp add --scope project --header "Authorization: Bearer YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp
Added HTTP MCP server context7 with URL: https://mcp.context7.com/mcp to project config
Headers: {
  "Authorization": "[REDACTED]"
}
File modified: ./.mcp.json

コマンドの画面ではキーが[REDACTED]に伏せられますが、.mcp.jsonにはキーが平文で書かれます。

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

stdio方式だと"type": "stdio"・"command": "npx"・"args"に--api-keyとキーが並び、空の"env": {}も付きます。つまりprojectスコープでAPIキーを直接渡すと、キーがリポジトリに入るファイルに残ります。チームで共有する.mcp.jsonにキーを書かない運用にしたいときは、userかlocalスコープを使います。

追加直後の状態はclaude mcp getで見られます。

$ claude mcp get context7
context7:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: http
  URL: https://mcp.context7.com/mcp
  Headers:
    Authorization: Bearer YOUR_API_KEY

引数の順番で名前が消える

--headerは複数の値を受け取れるオプション(ヘルプでは--header <header...>)なので、--header "..."の直後にサーバー名を置くと名前まで値として食べられます。v2.1.287で実際に起こした結果がこれです。

$ claude mcp add --scope project --transport http --header "Authorization: Bearer K" t1 https://mcp.context7.com/mcp
error: missing required argument 'name'

上の手順のように--headerの後ろに--transportのような別のオプションを挟むか、サーバー名とURLを先に書くと通ります。stdioで-e KEY=値を使うときは、サーバー名を先に置き、--の後ろにコマンドを書きます。

プラグインで入れる — Node.jsもAPIキーも要らない経路

Context7のプラグインは、ホスト済みのMCPサーバー(https://mcp.context7.com/mcp)にClaude Codeをつなぎます。追加されるツールはresolve-library-idとquery-docsです。ローカルのNode.js・npm・npxは不要です。Claude Code内で次の2コマンドを実行します。

/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplace

インストール後はClaude Codeを再起動し、/mcpでContext7を選んでブラウザのサインインに進みます。APIキーは要りません。注意点は、プラグインがCONTEXT7_API_KEYを読まないことです。ヘッドレス・SSH・CIのホストでAPIキーを使うなら、npx ctx7 setup --claudeかclaude mcp addの手動設定が必要です。

APIキーは必須か — 無料枠とレート制限

APIキーなしでもContext7 MCPは動きます。リポジトリのREADMEも「API Key Recommended」という表現で、必須ではなく推奨の扱いです。ただしAPIキーなしのアクセスはレート制限が低く、カスタム設定も使えません。

APIキーはcontext7.com/dashboardで無料発行できます。発行したキーはプランに応じて上限が上がる仕組みです。上限を超えるとHTTPステータス429が返ります。ヘッダーのRetry-After(再試行までの秒数)・RateLimit-Remaining(残り回数)・RateLimit-Reset(リセット時刻のUnix時間)で状況が分かります。現在の使用量とリセットの窓はダッシュボードで見られます。

ctx7コマンドには、--api-keyのほかにexport CONTEXT7_API_KEY=your_keyという渡し方もあります。ctx7 libraryとctx7 docsはログインなしでも動き、ログインすると上限が上がります。MCPサーバーへ渡す経路ごとの違いは、次のとおりです。

精度を上げる書き方 — ライブラリIDとバージョン指定

Context7は自然言語のプロンプトからライブラリを推測してドキュメントを検索しますが、名前が曖昧なライブラリやバージョン違いでAPIが変わるケースでは、明示的に指定したほうが正確な結果を得られます。

ライブラリIDを直接指定する場合、/org/project形式のIDをプロンプトに含めます。

Implement basic authentication with Supabase. use library /supabase/supabase for API and docs.

バージョンを指定する場合は、プロンプトにバージョン番号を書くだけでContext7が適切なドキュメントに一致させます。

How do I set up Next.js 14 middleware? use context7

ライブラリIDが分からない場合は、ctx7 library <名前> <やりたいこと>で検索できます。結果にはライブラリID・インデックス済みコード例の数・Source Reputation(情報源の信頼度)・Benchmark Score(品質スコア)が含まれ、名前が近く、コード例の数が多く、Source Reputationが高いものが選ぶ目安になります。

ctx7 library react "useEffectのクリーンアップを非同期処理でどう書くか"

自動的にContext7を使わせる — CLAUDE.mdにルールを書く

毎回のプロンプトに「use context7」と書かなくても、CLAUDE.mdにルールを1行加えておけば自動的に呼び出されるようになります。公式が例示しているルール文は次の通りです。

Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.

ctx7 setupでMCPサーバーモードを選ぶと、同じ趣旨のルールファイルがエージェントのルール用ディレクトリに書き込まれます。claude mcp addやプラグインで入れた場合に自動で呼ばせたいときは、上のルールをCLAUDE.mdに足す手があります。

よくあるつまずき

導入で起きやすい失敗と対処です。

• 401エラーで接続に失敗する: Context7のAPIのエラー表では、401は「APIキーが無効」で、形式はctx7skで始まるものと案内されています。キーの貼り間違いを疑います。このほか、ライブラリがまだ確定していないと202、検索失敗で503、処理の時間切れで504が返ります。いずれもREST APIの表なので、MCPの画面でも同じ番号が出るとは限りません。
• OAuthの認証画面に進まない: ローカルでnpx起動するstdio接続になっていないかを見ます。条件は上の「OAuth接続はリモートHTTP限定」のとおりです。
• サーバー名が足りないと言われる: --header "..."の直後にサーバー名を置いたときのエラーです。直し方は上の「引数の順番で名前が消える」にあります。
• ライブラリが見つからない: ライブラリIDの表記が間違っているか、そのライブラリがまだContext7に登録されていません。ctx7 libraryで正しいIDを検索し直します。
• ドキュメントが古い・薄い: Source Reputationやコード例の数はctx7 libraryの結果に出るので、別の候補があれば切り替えます。
• 社内ネットワークでnpxが失敗する: オンプレミス版を運用しているなら、ctx7 setup --mcp --base-urlで内部URLを明示します(/mcpや/apiは付けません)。--base-urlはMCPモード限定で、--oauth・--stdio・--cliとは併用できません。この指定では、更新確認とテレメトリを省き、ルールやスキルもGitHubやContext7 Cloudから取らずに同梱のものを使います。制限された環境では、ctx7を社内のnpmレジストリにミラーし、インストール済みのバイナリを実行する形が案内されています。
• 社内ポリシーでテレメトリを送りたくない: ctx7 CLIは既定で匿名の利用データを収集します。CTX7_TELEMETRY_DISABLED=1をコマンドの前に付けるとその1回だけ無効化でき、シェルの設定ファイルに恒久的に書けば常時オフにできます。

他の経路からもContext7へ到達できる

Claude Codeのclaude mcp add以外にも、Context7へ到達する経路はいくつかあります。VS Code(GitHub Copilot Chat)のmcp.jsonから同じ@upstash/context7-mcpを登録する方法はVS Code MCP設定ガイドで扱っています。Docker MCP Catalogにもリモートサーバーとして収録されています。ゲートウェイ経由で他のコンテナ化サーバーと一緒に管理したい場合はDocker MCP ToolkitでClaude Codeからコンテナを操作する設定が手順を扱います。

まとめ

どの経路でも、入るのは同じ2つのツールです。違うのは、キーがどこに残るか(.mcp.jsonか、ユーザー設定か、OAuthでキー自体を持たないか)なので、共有リポジトリに載るファイルへ書かれるかどうかで選ぶ手があります。