CSV Analyzer MCP Server

CSV アナライザー MCP サーバー

MCP に対応したあらゆるクライアントから呼び出せるツールとして、CSV 分析を提供する軽量な MCP サーバーです。

CSV の生データを渡すと、行数、型の検出、NULL 率、重複、分布、外れ値の検出など、構造化された統計情報を JSON または Markdown で取得できます。

---

MCP とは？

Model Context Protocol は、AI アシスタントが外部ツールを呼び出せるようにするオープン標準です。このサーバーは CSV 分析を MCP ツールとして提供するため、Claude に「この CSV を分析して、NULL が最も多い列を教えて」や「収益が 10000 を超える行をフィルタリングしてから、結果を分析して」といったことを依頼し、実際に計算された結果を取得できます。

---

機能

• 列ごとの分析 — 型の検出、NULL 率、一意な値、最小値／最大値／平均値／中央値／標準偏差、四分位数、最頻値、日付範囲
• 頻度分布 — 任意の列について、値の出現回数と割合をランキング形式で表示
• 外れ値の検出 — すべての数値列に対し、IQR 法と z スコア法を使用
• 行のフィルタリング — 列の条件でフィルタリングし、さらに分析を連鎖して実行
• データのプレビュー — 分析前に、先頭 N 行を Markdown テーブルで確認
• CSV の比較 — スキーマ、行の内容、またはその両方で 2 つのファイルを比較
• データのクリーニング — 分析前に重複の削除や NULL を含む行の削除を任意で実行
• 2 種類の出力形式 — プログラムでの利用に適した構造化 JSON、または読みやすい要約を表示する Markdown
• カスタム区切り文字 — コンマ、セミコロン、タブ、パイプ、その他任意の区切り文字に対応
• コンテンツベース — ファイルパスではなく CSV の生テキストを受け付けるため、安全でリモート環境にも対応

---

インストール

前提条件： Python ≥ 3.12 および uv

git clone https://github.com/juanmaalt/csv_analyzer_mcp_server.git
cd csv_analyzer_mcp_server
uv sync

---

MCP クライアントへの接続

Claude Desktop

次の内容を claude_desktop_config.json に追加してください （macOS では通常 ~/Library/Application Support/Claude/claude_desktop_config.json にあります）。

{
  "mcpServers": {
    "csv_analyzer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/csv_analyzer_mcp_server",
        "python",
        "main.py"
      ]
    }
  }
}

Cursor / VS Code（MCP 拡張機能）

{
  "mcp": {
    "servers": {
      "csv_analyzer": {
        "command": "uv",
        "args": [
          "run",
          "--directory",
          "/absolute/path/to/csv_analyzer_mcp_server",
          "python",
          "main.py"
        ]
      }
    }
  }
}

設定を保存した後、クライアントを再起動してください。すべてのツールが使用可能なツール一覧に表示されます。

---

使用可能なツール

analyze_csv

CSV ファイルの統計を包括的に分析します。型、NULL 率、一意な値の数、型に応じた統計情報を含む、列ごとの要約を返します。

パラメーター	型	デフォルト	説明
csv_content	str	必須	CSV の全文（ファイルパスではありません）
delimiter	str	","	値を区切る文字
remove_duplicates	bool	True	分析前に完全に重複する行を削除
remove_non_valid_data	bool	True	分析前に欠損または空のフィールドを含む行を削除
output_format	str	"json"	"json" または "markdown"

JSON 出力の構造：

{
  "total_rows": 38,
  "rows_removed": 2,
  "columns": {
    "age": {
      "null_count": "N/A",
      "null_percentage": "N/A",
      "duplicate_count": "N/A",
      "unique_values": 22,
      "type": "int",
      "min": 19,
      "max": 74,
      "avg": 43.5,
      "median": 42.0,
      "std": 14.2,
      "q25": 31.0,
      "q75": 57.0
    },
    "plan_type": {
      "null_count": "N/A",
      "null_percentage": "N/A",
      "duplicate_count": "N/A",
      "unique_values": 3,
      "type": "string",
      "most_repeated_value": "Premium",
      "top_values": [
        {"value": "Premium", "count": 18},
        {"value": "Basic", "count": 12},
        {"value": "Enterprise", "count": 8}
      ]
    }
  }
}

---

get_csv_preview

CSV の先頭 N 行を Markdown テーブルで返します。完全な分析を実行する前に、構造や値を確認するのに便利です。クリーニングは適用されません。

パラメーター	型	デフォルト	説明
csv_content	str	必須	CSV の全文
delimiter	str	","	値を区切る文字
n_rows	int	5	返す行数

出力例：

| customer_id | age | plan_type | monthly_fee |
| --- | --- | --- | --- |
| 1001 | 34 | Premium | 49.99 |
| 1002 | 27 | Basic | 19.99 |

---

filter_csv

列の条件に基づいて行をフィルタリングし、結果を CSV 文字列として返します。出力は analyze_csv やその他のツールにそのまま渡せます。

Parameter	Type	Default	Description
csv_content	str	required	CSV 全体のテキスト内容
column	str	required	フィルタリング対象の列名
operator	str	required	次のいずれか：>、<、>=、<=、==、!=、contains
value	str	required	比較する値（列の型に自動変換されます）
delimiter	str	","	値を区切る文字

対応する演算子：

Operator	Behavior
> < >= <=	数値の比較
== !=	等価性（すべての型で使用できます）
contains	文字列列に対する、大文字と小文字を区別しない部分文字列の照合

---

get_column_distribution

指定した列の順位付き度数表を返します。各値の出現回数と、行全体に占める割合を示します。

Parameter	Type	Default	Description
csv_content	str	required	CSV 全体のテキスト内容
column	str	required	分析する列名
delimiter	str	","	値を区切る文字
top_n	int	10	返す値の最大数

出力例：

[
  {"value": "Premium", "count": 18, "percentage": 45.0},
  {"value": "Basic", "count": 12, "percentage": 30.0},
  {"value": "Enterprise", "count": 8, "percentage": 20.0}
]

---

detect_outliers

IQR または z-score を使用して、数値列の外れ値を含む行を検出します。フラグが付けられた行を、列名、値、理由とともに返します。

Parameter	Type	Default	Description
csv_content	str	required	CSV 全体のテキスト内容
delimiter	str	","	値を区切る文字
method	str	"iqr"	"iqr" または "zscore"
columns	list[str]	None	チェックする特定の列。省略した場合は、すべての数値列をチェックします

手法：

• iqr — Q1 - 1.5 * IQR 未満または Q3 + 1.5 * IQR を超える値にフラグを付けます
• zscore — 平均から標準偏差 3 つ分を超えて離れた値にフラグを付けます

出力例：

[
  {"row_index": 4, "column": "monthly_fee", "value": 999.99, "reason": "outside IQR bounds [10.5, 89.3]"},
  {"row_index": 21, "column": "age", "value": 3, "reason": "outside IQR bounds [22.0, 68.0]"}
]

---

compare_csvs

スキーマ（列の差異）および／または行の内容に基づいて、2 つの CSV ファイルを比較します。同じデータセットのバージョン間の変更を検出するのに便利です。

Parameter	Type	Default	Description
csv_content_a	str	required	1 つ目のファイルの CSV 全体のテキスト内容
csv_content_b	str	required	2 つ目のファイルの CSV 全体のテキスト内容
delimiter	str	","	両方のファイルで値を区切る文字
mode	str	"both"	"schema"、"rows"、または "both"

出力例（mode="both"）：

{
  "schema": {
    "columns_only_in_a": ["notes"],
    "columns_only_in_b": ["region"],
    "common_columns": ["client", "revenue", "date"]
  },
  "rows": {
    "total_rows_a": 25,
    "total_rows_b": 28,
    "rows_only_in_a": 4,
    "rows_only_in_b": 7,
    "common_rows": 21
  }
}

---

ツールの組み合わせ

ツールは連鎖して使えるように設計されています。便利なパターンをいくつか紹介します。

# Preview first, then analyze
get_csv_preview → analyze_csv

# Filter a subset, then analyze it
filter_csv (churned == True) → analyze_csv

# Check distribution before deciding how to filter
get_column_distribution → filter_csv → analyze_csv

# Find outliers, then filter them out and re-analyze
detect_outliers → filter_csv (!= outlier_value) → analyze_csv

---

設定

設定はプロジェクトのルートにある .env ファイルから読み込まれます。

Variable	Default	Description
MAX_ROWS_TO_ANALYZE	500	リクエストごとに処理する行の最大数
DEFAULT_OUTPUT_FORMAT	markdown	フォールバック時の出力形式
MAX_PREVIEW_ROWS	10	要約に含めるプレビュー行の数
NULL_THRESHOLD_WARNING	0.3	警告を表示する欠損値率のしきい値
OUTLIER_STDDEV_CUTOFF	3.0	外れ値検出に使用する z-score のしきい値

---

プロジェクト構成

csv_analyzer_mcp_server/
├── core/
│   ├── loader.py        # CSV string → pandas DataFrame
│   ├── analyzer.py      # Per-column statistics, distribution, outlier detection, comparison
│   ├── formatter.py     # JSON / Markdown output, table preview
│   └── transformer.py   # Column name normalization, row filtering
├── config/
│   └── settings.py      # Environment-based configuration
├── data/                # Sample CSV files for testing
├── main.py              # MCP server entry point — all tool definitions
├── pyproject.toml       # Project metadata and dependencies
└── .env                 # Local configuration (not committed)

---

サンプルデータ

テスト用に、3 つのサンプル CSV ファイルが data/ に含まれています。

File	Rows	Description
sample_data_usage.csv	40	通信事業者の顧客利用状況（年齢、プラン、データ、解約）
sample_heart_checks.csv	40	医療記録（コレステロール、血圧、糖尿病、心疾患）
sample_project_revenue.csv	25	意図的に欠損値を含めたプロジェクトの請求データ

---