Claude CodeでPinecone MCPを使い、インデックスの作成と検索を任せる

Pinecone MCPサーバーでClaude Codeにできること

Pinecone MCPサーバーは、ベクトルデータベースPineconeの操作とドキュメント検索を、Claude Codeから呼べるツールとして公開します。Pinecone自身が提供するサーバーで、npmパッケージ@pinecone-database/mcpをnpxで起動するローカル(stdio)型です。

Claude Codeに任せられる作業は、次のとおりです。

• インデックスの一覧表示と設定の確認
• 埋め込みモデルつきインデックスの新規作成
• テキストレコードの投入(upsert)
• 自然文での検索と、メタデータによる絞り込み
• 複数インデックスをまたぐ検索と、結果の再ランク
• Pineconeのドキュメント検索(コード生成前の調べもの)

つまり、SDKのコードを書かせるだけでなく、自分のPineconeアカウントに対して実際に操作を実行させられます。同じ位置づけのベクトル検索系では、Qdrant MCPサーバーが「記憶の保存と検索」に絞った2ツール構成でした。Pineconeはインデックス管理まで含むぶん、ツールの数が多くなります。

使えるツール9個と、使えないインデックス

Pinecone MCPサーバーのツールは、ドキュメントの一覧で次の9個です。

この一覧にはインデックスやレコードの削除に当たるツールがありません。壊す操作はupsertによる上書きまでに限られます。

最大の制約は、対象が統合埋め込み(integrated embedding)のインデックスだけという点です。ドキュメントは「外部の埋め込みモデルで作ったベクトルを入れたインデックスは未対応」と明記しています。自前でベクトルを計算して投入している既存インデックスには、このMCPサーバー経由で検索をかけられません。

統合埋め込みのインデックスとは、Pinecone側のホスト型モデルがテキストをベクトルに変換してくれるインデックスです。upsertでも検索でも、渡すのは生のテキストだけで済みます。Claude Codeに「文を入れて」「この質問で探して」と頼む使い方と相性がよい構成です。

ツール数が公式ページ間で食い違う

同じPineconeの情報源でも、ツールの数え方が違います。

• Pinecone docsのMCPサーバーのページ: 9個(上の表)
• ClaudeマーケットプレイスのPineconeプラグインのページ: 「7つのツール」とし、search-docsとcascading-searchを挙げていない

マーケットプレイス側の説明文が古い可能性はありますが、理由はどのページにも書かれていません。実際に何が公開されているかは、接続したあとにClaude Code上の/mcpで確認できます。説明文より、手元で見えるツール一覧を信頼してください。

接続前に用意するもの

Pinecone docsが挙げる前提は2つです。

• PineconeアカウントのAPIキー
• Node.jsがインストール済みで、nodeとnpxがPATHにあること

npmレジストリ上の@pinecone-database/mcpは、Node.js 20以上を要求しています(enginesの記載)。古いNodeが入っている環境では、先にバージョンを上げておくと起動失敗を避けられます。

接続方法は2通り

Claude CodeにPineconeを足す方法は、MCPサーバーだけを入れる手動設定と、公式プラグインを入れる方法の2つです。Pinecone docsも、手動設定は「MCPサーバーだけが欲しい人向け」と位置づけています。

手動設定: claude mcp add-json

Pinecone docsに載っているコマンドは次のとおりです。YOUR_API_KEYは自分のキーに置き換えます。

claude mcp add-json pinecone-mcp \
  '{"type": "stdio",
    "command": "npx",
    "args": ["-y", "@pinecone-database/mcp"],
    "env": {"PINECONE_API_KEY": "YOUR_API_KEY"}}'

docsの手順では、追加後にClaude Codeを再起動し、/mcpで状態を確かめます。ドキュメントの例では、pinecone-mcp: ✓ connectedと表示されます。

claude mcp addのフラグで書くと、次の形になります。--より前がClaude Code自身のオプション、後ろがサーバーの起動コマンドです。

claude mcp add pinecone-mcp \
  --env PINECONE_API_KEY=YOUR_API_KEY \
  -- npx -y @pinecone-database/mcp

どちらで追加しても、サーバー名はpinecone-mcpにしています。あとで権限ルールを書くとき、この名前がツール名の一部になるためです。名前を変えるなら、以降の例も合わせて変えてください。

プラグイン: claude plugin install

プラグインの前提は、手動設定より1つ多くなります。APIキー、公式AnthropicマーケットプレイスにアクセスできるClaude Code、npx、そして同梱のPythonスクリプトを動かすためのuvです。Pinecone CLIは任意です。

手順は3段階で、キーは環境変数に置きます。

プラグインのスキルはPinecone docsの表で9行あります(Help、Quickstart、Query、Assistant、CLI、Full-text search、n8n、MCP、Docs)。MCPサーバーのページが「8 skills」と書く一方、表は9行なので、数は参考程度に見てください。インデックスの検索だけなら/pinecone:query、MCPツールの一覧を引くなら/pinecone:mcpが入口になります。

マーケットプレイスのページによると、APIキーはClaude Codeを起動する前にPINECONE_API_KEYとして設定しておく必要があります。起動後にexportしても、すでに立ち上がったセッションには効かない点に注意してください。

インデックスの作成と検索を頼む

接続できたら、自然文で頼みます。Pinecone docsは、同じ依頼を2通りの形で例示しています。

• コード生成: 「密ベクトルの統合埋め込みインデックスを作り、犬に関する文を20件upsertし、10秒待って検索し、再ランクするPythonスクリプトを書いて」
• 作業の実行: 同じ内容を、スクリプトではなく実際のPinecone操作として実行させる

前者はPinecone MCPのsearch-docsで最新のSDKの書き方を調べさせるだけで、アカウントは変わりません。後者はアカウントに対して実際にインデックスを作ります。どちらを頼んでいるのかが曖昧だと、意図せず課金対象のリソースを作りかねません。依頼文には「スクリプトを書くだけ」「実際に実行する」のどちらかを必ず入れてください。

実行まで任せる場合の依頼文は、たとえば次のようになります。これはドキュメントの例を日本語にした一例です。

Pineconeに、統合埋め込みの密ベクトルインデックスを新規作成してください。
作成後に、犬に関する短い文を20件upsertし、10秒待ってから
「散歩の習慣」で検索して、結果を再ランクしてください。
実行前に、作成するインデックス名と設定を教えてください。

最終行の「実行前に設定を教えてください」が効きます。create-index-for-modelは、モデルや次元数といった設定を決めて作る操作です。作る前に内容を確認させておけば、あとからdescribe-indexで調べ直す手間が減ります。

操作の流れは、ツールの役割から次の順になります。

「投入直後に検索すると結果が空になる」という挙動を、Pineconeのドキュメントがこのページで明示しているわけではありません。ここで言えるのは、例の依頼文が10秒待つ手順を入れているところまでです。

Claude Code側の設定で事故を減らす

ここからは、Pinecone docsにはない、Claude Code側の運用の話です。

権限ルールで読み取りと書き込みを分ける

MCPツールの権限ルールは、mcp__<サーバー名>__<ツール名>の形で書きます。サーバー名をpinecone-mcpにした場合の、読み取り専用ツールだけを自動許可する例は次のとおりです。

{
  "permissions": {
    "allow": [
      "mcp__pinecone-mcp__search-docs",
      "mcp__pinecone-mcp__list-indexes",
      "mcp__pinecone-mcp__describe-index",
      "mcp__pinecone-mcp__describe-index-stats",
      "mcp__pinecone-mcp__search-records"
    ]
  }
}

create-index-for-modelとupsert-recordsはallowに入れないでおくと、実行のたびに確認が出ます。サーバー単位でまとめるならmcp__pinecone-mcp__*と書けますが、書き込み系まで一括で許可することになります。ルールの構文はMCPの権限構文で詳しく扱っています。

プラグイン経由の場合、サーバー名はpinecone-mcpではなく、プラグイン名を含む形に変わります。Claude Codeのドキュメントによると、プラグイン同梱のMCPサーバーのツールはmcp__plugin_<プラグイン名>_<サーバー名>__<ツール名>になります。手動設定と同じルールをコピーしても、プラグイン側のツールには当たりません。プラグイン内のサーバー名はPinecone docsに記載がないため、/mcpで表示される名前を確認してから書いてください。

チームで共有するときはキーを展開する

プロジェクト全体で使うなら、.mcp.jsonに書いてコミットする方法があります。APIキーを直接書かず、環境変数の展開を使います。.mcp.jsonのenvには${VAR}が使えます。

{
  "mcpServers": {
    "pinecone-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pinecone-database/mcp"],
      "env": {
        "PINECONE_API_KEY": "${PINECONE_API_KEY}"
      }
    }
  }
}

各メンバーが自分のシェルでPINECONE_API_KEYを設定していれば、同じ設定ファイルで動きます。未設定のままだと${PINECONE_API_KEY}の文字列がそのまま渡され、claude mcp listと/mcpに警告が出ます。プロジェクトスコープのサーバーは、初回に承認が必要です。

大きな検索結果は出力上限に当たる

MCPツールの出力が10,000トークンを超えると警告が出て、既定では25,000トークンで打ち切られます。上限は環境変数MAX_MCP_OUTPUT_TOKENSで変えられます。search-recordsで多数のレコードを返させる依頼では、件数を絞るほうが先です。

接続できないときの切り分け

症状別の見る場所を、次の表にまとめます。

試す順番

Claude CodeからPineconeを使い始めるなら、まずは手動設定で読み取りツールだけを許可し、list-indexesとdescribe-indexで既存の状態を見せるところから入る形があります。書き込みが必要になった時点で、create-index-for-modelとupsert-recordsを都度承認しながら試せば、課金や上書きの範囲を自分で把握できます。同じ「データベースの管理をClaudeに任せる」型の記事に、MongoDB Atlasのクラスタ管理があります。

MCPの追加方法そのものはClaude Code MCP設定ガイドにまとめています。