Grips Intelligence MCPサーバー (v2)

Grips IntelligenceのEコマースデータAPIを、Claude Desktop、Cowork、Claude CodeなどのあらゆるMCPクライアントに公開するModel Context Protocol (MCP) サーバーです。

v2はv1をクリーンに再構築したもので、初日から防御的なデータ処理が組み込まれています。v1.xで実行時のパッチが必要だった「.map is not a function」系のバグを修正しました。データが少ない、または不明なドメインの場合でも、ツール呼び出しがクラッシュするのではなく、クリーンな「データなし」のレスポンスを返すようになります。

含まれるもの

すべてのツールは、読みやすさのためにデフォルトでMarkdown形式で出力します。機械可読な出力が必要な場合は format: "json" を渡してください。

インストール

npm install

prepareスクリプトは、npm installを実行すると自動的に dist/ をビルドします。

設定

MCPクライアントのサーバー設定にGrips APIキーを設定してください。Claude Desktopの場合は ~/Library/Application Support/Claude/claude_desktop_config.json です：

{
  "mcpServers": {
    "grips": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/grips-mcp-server-v2/dist/index.js"
      ],
      "env": {
        "GRIPS_API_KEY": "your-api-key-here",
        "GRIPS_DEFAULT_COUNTRY": "US"
      }
    }
  }
}

必要な環境変数：

• GRIPS_API_KEY — Grips APIトークン (grips-api-key ヘッダーとして送信されます)。

オプションの環境変数：

• GRIPS_DEFAULT_COUNTRY — US、GB、または DE。未設定または無効な場合は US がデフォルトとなります。

設定を編集した後、Claude Desktopを完全に終了し（ウィンドウを閉じるだけでなく Cmd+Q で終了）、再起動してください。

v1との違い

v1は特定のAPIレスポンス形式でクラッシュしていました。Gripsがデータ範囲の狭いドメインや不明なドメインを返した際、timeseries フィールドが null や undefined、[] ではなく {} として返されるためです。コードでは (data.timeseries ?? []).map(...) を使用していましたが、これは null/undefined に対してのみ有効で、{} には対応していませんでした。結果として "data.timeseries ?? []).map is not a function" というエラーが発生していました。

v2では、すべてのペイロードフィールドを使用前に toArray<T>() (配列用) または toObject<T>() (デバイスエンドポイントのような辞書形式のレスポンス用) を通すようにしました。配列やオブジェクトではない値は安全な空のデフォルト値にフォールバックされ、ツールは例外を投げる代わりにクリーンな「データなし」のレスポンスを返します。

その他の変更点：

• 日付の正規化がすべてのツールで一貫しています（すべてUTCの YYYY-MM-DD に変換されるため、UTC以外のタイムゾーンでも日付の境界でデータがずれることはありません）。

• 通貨 / 整数 / パーセントのフォーマッタは、値が欠落している場合に $NaN や 0.00% ではなく — を表示します。

• エラーメッセージにアクション可能なヒントが含まれるようになりました（401 → 「APIキーを確認してください」、429 → 「レート制限です、期間を短くしてください」など）。

• grips_compare_domains におけるドメインごとのエラー分離 — 8ドメインの比較中に1つのドメインでデータが不足していても、他の7つの結果が壊れることはありません。

• 文字数制限の切り詰め — レスポンスは約200KBでキャップされ、目に見える通知が表示されるため、複数ドメインの取得によってコンテキストウィンドウが溢れることはありません。

開発

npm run dev    # watch mode, rebuilds on change
npm run build  # one-shot build to dist/

コマンドラインからのテスト

サーバーがエラーなしで起動することを確認します（stdinからのEOFで終了します）：

GRIPS_API_KEY=your-key node dist/index.js < /dev/null

stderrに [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). と表示され、クラッシュしないことを確認してください。

インタラクティブなテストには @modelcontextprotocol/inspector を使用してください：

npx @modelcontextprotocol/inspector node dist/index.js

APIリファレンス

Gripsは公開スキーマを https://gripsintelligence.com/knowledge-base/api で文書化しています。このサーバーが使用するクエリは、そのページからそのままコピーしたものです。

現在サポートされている国：US、GB、DE。それ以外はAPIでエラーになります。

ライセンス

プライベート — 外部配布不可。