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

Context7 MCPとは

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

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

セットアップは2方式 — MCPサーバーとCLI + Skillsの違い

Context7の接続方式は2つあります。MCPサーバーモードはMCPプロトコルでツールを直接呼び出す方式、CLI + Skillsモードはctx7コマンドを実行するSkillをエージェントに教える方式です。どちらも取得できるドキュメントの中身は同じですが、動作の仕組みが異なります。

Claude Codeで最短で終わらせたいなら、両方式に対応するctx7 setupコマンドが早道です。設定内容を手元で把握したい場合はclaude mcp addを直接使います。

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

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

Claude Codeがプロンプト中の「use context7」を検知すると、まずresolve-library-idでライブラリを特定し、続けてquery-docsでドキュメントを取得する2段階の呼び出しになります。

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

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

# インストールなしで実行し、対話式でモードとエージェントを選ぶ
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サーバーの登録先(Claude Codeなら.mcp.json)、エージェントへの利用ルールファイル、context7-mcpという名前のSkillの3種類です。設定を取り消すには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

どちらの方式でも設定スコープはuser(全プロジェクト共通)・project(チーム共有)・local(このプロジェクトのみ)から選べます。claude mcp addの構文全体、スコープの使い分け、OAuth認証の詳細はClaude Code MCP設定ガイドにまとめています。

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

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

APIキーはcontext7.com/dashboardで無料発行できます。発行したキーはプランに応じて上限が上がる仕組みで、超過するとHTTPステータス429が返り、Retry-Afterヘッダーで再試行までの待機秒数が分かります。個人利用でリクエスト数が少ないなら未設定でも支障は出にくく、チームで共有するCIパイプラインなど呼び出し頻度が高い用途ではAPIキーを発行しておくと安定します。

APIキーの渡し方は--api-keyフラグだけではありません。export CONTEXT7_API_KEY=your_keyのように環境変数として設定しておけば、対話的なログインを省略できます。CI環境など毎回フラグを書きたくない場合はこちらが便利です。

精度を上げる書き方 — ライブラリ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(品質スコア)が含まれ、名前が近く採用実績の多いものを選ぶ目安になります。

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.mdやエージェント向けルールファイルに自動で書き込まれます。手動でclaude mcp addだけを実行した場合はルールは書き込まれないため、CLAUDE.mdへの追記は自分で行う必要があります。

よくあるつまずき

Context7 MCPの導入で報告の多い失敗パターンです。

• 401エラーで接続に失敗する: APIキーの形式が誤っている可能性があります。Context7のAPIキーはctx7skで始まる文字列です。別サービスのキーを貼っていないか確認します。
• OAuthの認証画面に進まない: stdio接続(ローカルでnpx起動する方式)はOAuthに対応していません。エンドポイントを/mcp/oauthに変えるのはリモートHTTP接続のときだけです。
• ライブラリが見つからない: ライブラリIDの表記が間違っているか、そのライブラリがまだContext7に登録されていません。ctx7 libraryで正しいIDを検索し直します。
• ドキュメントが古い・薄い: マイナーなライブラリはインデックス済みのコード例が少なく、Source Reputationが低いことがあります。ctx7 libraryの結果でコード例の数とスコアを確認し、別の候補があれば切り替えます。
• 社内ネットワークでnpxが失敗する: プロキシやレジストリのミラー設定が必要になることがあります。オンプレミス版を運用している場合は、ctx7 setup --mcp --base-urlで内部URLを明示します(--base-urlはMCPモード限定で、--oauth・--stdio・--cliとは併用できません)。
• 社内ポリシーでテレメトリを送りたくない: 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 Toolkitのカタログにも組み込みエントリとして収録されており、ゲートウェイ経由で他のコンテナ化サーバーと一緒に管理したい場合はDocker MCP ToolkitでClaude Codeからコンテナを操作する設定が手順を扱います。

まとめ

Context7 MCPは、ctx7 setupでの自動設定とclaude mcp addでの手動設定のどちらでもClaude Codeに接続できます。APIキーは必須ではありませんが、レート制限を上げたい場合や継続的に使う場合は無料で発行しておくと安定します。ライブラリIDやバージョンを明示するプロンプトの書き方を覚えておくと、曖昧な検索よりも安定して正確なドキュメントを取得できます。