Sales Analytics MCP Server

カスタム Model Context Protocol (MCP) サーバー。Claude Desktop にライブな販売データベースへの直接的かつ安全なアクセスを提供し、Python 製アナリティクスバックエンドを、MCP 互換の AI アシスタントならどれでも使える再利用可能なツールに変えます。アプリケーションごとに統合を書く必要はありません。

MCP とは何か、そしてなぜサーバーを構築するのか

Model Context Protocol は、AI アシスタントが外部ツールやデータソースに共通のインターフェースを通じて接続できるようにするオープンスタンダード（Anthropic が作成）です。アシスタントごとにツールごとのカスタム統合を構築する必要はありません。MCP サーバーを書くということは、データソースごとに接続を一度だけ構築することを意味し、あらゆる MCP 互換クライアント（Claude Desktop、Claude Code、その他の MCP 対応アプリケーション）が、アプリケーションごとの作り直しなしですぐに利用できます。

このプロジェクトは、実際の PostgreSQL 販売データベース（ai-analytics-agent と同じもの）を MCP ツール群として公開し、Claude がスキーマの調査、クエリ実行、異常検知を、通常の会話の中で直接行えるようにします。

Related MCP server: pg-mcp

アーキテクチャ

graph LR
    A[Claude Desktop] -->|MCP protocol| B[Sales Analytics<br/>MCP Server]
    B --> C[get_database_schema]
    B --> D[run_sql_query]
    B --> E[find_sales_anomalies]
    C --> F[(Supabase / PostgreSQL)]
    D --> F
    E --> F

公開されているツール

技術スタック

エンジニアリングノート

• 開発中に SDK の破壊的変更を発見: MCP Python SDK は、このプロジェクトの構築中にメジャーバージョン（2.0.0）をリリースし、FastMCP を MCPServer にリネームしてインポートパスも変更しました。サーバーは古いバージョンに固定せず新しい API に更新されたため、コードは現在の SDK の表面を反映しています。

• Claude は独自のツール戦略を選ぶ: find_sales_anomalies が存在する前に異常を探すよう依頼されたとき、Claude は独自に run_sql_query を使って調査しました — 重複行、負の金額、カテゴリ別の内訳を自らの判断でチェックし、専用ツールが後に確認したのと同じ根本原因に到達しました。これは、LLM クライアントが汎用ツールと専用ツールのどちらを選ぶか、必ずしも「明白な」専用関数を優先するわけではないことを示す有益な例です。

• Text-to-SQL エージェントと同じ安全モデル: run_sql_query は、Python ベースの Text-to-SQL プロジェクトと同じ読み取り専用ガードレールのアプローチを再利用しています。これは、安全性ロジックを一度だけ慎重に構築することが、独立した 2 つ目のツールで再利用されたときに報われる良い例です。

セットアップ

1. 依存関係をインストールします: pip install -r requirements.txt

2. .env ファイルを作成します: DATABASE_URL=your_postgresql_connection_string

3. サーバーを Claude Desktop の設定ファイル（claude_desktop_config.json）に追加します:

   {
     "mcpServers": {
       "sales-analytics": {
         "command": "python",
         "args": ["/full/path/to/server.py"]
       }
     }
   }

4. Claude Desktop を完全に再起動します（ウィンドウを閉じるだけでなく、タスクマネージャー / アクティビティモニターから終了します）

5. 新しいチャットを開始して、Claude に次のような質問をします:

   "What tables are available, and are there any sales anomalies I should know about?"

対話の例

Wait, I need to check if the last line is prose or just an image. It's an image with alt text "Claude Desktop using the MCP server" - I should translate it to Japanese: "Claude Desktop が MCP サーバーを使用している様子"

Let me also check the question in the setup section: "What tables are available, and are there any sales anomalies I should know about?" - this should be translated.# Sales Analytics MCP Server

カスタム Model Context Protocol (MCP) サーバー。Claude Desktop に実稼働中の販売データベースへの直接的かつ安全なアクセスを提供し、Python 製アナリティクスバックエンドを、MCP 互換の AI アシスタントならどれでも利用できる再利用可能なツールに変えます。アプリケーションごとの統合を書く必要はありません。

MCP とは何か、なぜサーバーを構築するのか

Model Context Protocol は、AI アシスタントが外部ツールやデータソースに共通のインターフェースを通じて接続できるようにするオープンスタンダード（Anthropic が作成）です。アシスタントごとにツールごとのカスタム統合を構築する必要はありません。MCP サーバーを書くということは、データソースごとに接続を一度だけ構築することを意味し、MCP 互換のクライアント（Claude Desktop、Claude Code、その他の MCP 対応アプリケーション）ならどれでも、アプリケーションごとの作り直しなしに即座に利用できます。

このプロジェクトは、実際の PostgreSQL 販売データベース（ai-analytics-agent で使われているものと同じ）を一連の MCP ツールとして公開するため、Claude は通常の会話の中で直接、スキーマの調査、クエリの実行、異常検知を行うことができます。

アーキテクチャ

graph LR
    A[Claude Desktop] -->|MCP protocol| B[Sales Analytics<br/>MCP Server]
    B --> C[get_database_schema]
    B --> D[run_sql_query]
    B --> E[find_sales_anomalies]
    C --> F[(Supabase / PostgreSQL)]
    D --> F
    E --> F

公開ツール

技術スタック

エンジニアリングノート

• SDK の破壊的変更を発見: MCP Python SDK が、このプロジェクトの開発中にメジャーバージョンをリリースし、FastMCP を MCPServer に改名してインポートパスを変更しました。サーバーは古いバージョンに固定するのではなく新しい API に更新されたため、現在の SDK サーフェスに準拠しています。

• Claude は独自にツールを選択: find_sales_anomalies が存在する前に異常を探すよう依頼された Claude は、汎用ツールである run_sql_query を自ら選択し、重複レコード、マイナス金額、カテゴリ別の内訳を調査しました。専用ツールが後に確認したのと同じ根本原因に、自ら到達したのです。これは、LLM が汎用ツールと専用ツールのどちらを選ぶのか、そして「専用関数があるからといって必ずそれを使うわけではない」ことを示す良い例です。

• Text-to-SQL エージェントと同じ安全性モデル: run_sql_query は、Text-to-SQL プロジェクトと同じ読み取り専用の安全ロジックを再利用しています。一度しっかりと安全ロジックを構築しておけば、独立した別のツールでも同じ安全性が活きるという好例です。

セットアップ

1. 依存関係をインストール: pip install -r requirements.txt

2. .env ファイルを作成: DATABASE_URL=your_postgresql_connection_string

3. サーバーを Claude Desktop の設定ファイル（claude_desktop_config.json）に追加:

   {
     "mcpServers": {
       "sales-analytics": {
         "command": "python",
         "args": ["/full/path/to/server.py"]
       }
     }
   }

4. Claude Desktop を完全に再起動します（タスクマネージャー / アクティビティモニターから終了し、ウィンドウを閉じるだけでは不十分）

5. 新しいチャットを開始し、Claude に次のような質問をします:

   「利用可能なテーブルは何ですか？注意すべき売上異常はありますか？」

対話の例