MCP Data Analyst

📊 数据分析MCP服务器

一 MCP（模型上下文协议） 将LLM转换为数据分析师的服务器。将其连接到数据库或数据文件并获得：

• 架构上下文 --LLM会自动看到您的表和列
• 安全SQL查询 --用自然语言提问，获取SQL结果
• 数据可视化 --生成图表和汇总统计数据

🏗️ 建筑

graph LR
    Client["MCP Client
(Claude / Gemini)"]
    Server["MCP Server
(FastMCP)"]
    Tools["Tools"]
    Resources["Resources"]
    DB["SQLite / CSV / Excel"]

    Client |"MCP Protocol
(stdio)"| Server
    Server --> Tools
    Server --> Resources

    subgraph Tools
        direction TB
        T1["get_schema"]
        T2["run_read_only_query"]
        T3["visualize_data"]
    end

    subgraph Resources
        R1["data://schema"]
    end

    Tools --> DB
    Resources --> DB

✨ 特性

📁 项目结构

MCP_Data_Analyst/
├── src/
│   ├── server.py            # MCP server entry point
│   ├── db.py                # Database engine (SQLite/CSV/Excel)
│   ├── resources.py         # MCP resources (schema context)
│   ├── logging_config.py    # Structured JSON logging setup
│   └── tools/
│       ├── query.py         # Read-only SQL query tool
│       └── visualize.py     # Chart generation tool
├── tests/
│   ├── conftest.py          # Shared fixtures (in-memory DB)
│   ├── test_db.py           # Schema, validation, execution tests
│   ├── test_tools.py        # Query + visualization tool tests
│   └── test_resources.py    # Resource formatting tests
├── data/                    # Data files directory
├── .github/workflows/
│   └── ci.yml               # GitHub Actions CI pipeline
├── Dockerfile               # Multi-stage Docker build
├── docker-compose.yml       # One-command Docker setup
├── create_sample_db.py      # Generates demo database
├── requirements.txt
└── pyproject.toml

🚀 快速开始

选项1:Docker（推荐）

docker-compose up --build

集装箱附带了一个预先构建的样本数据库。要使用您自己的数据，请将其放置在 data/ 目录和集合 DATA_SOURCE 在 docker-compose.yml.

选项2：本地

# Install dependencies
pip install -r requirements.txt

# Create sample database (optional)
python create_sample_db.py

# Run the server
python -m src.server

⚙️ 配置

设置 DATA_SOURCE 指向数据文件的环境变量：

如果 DATA_SOURCE 未设置，服务器使用 data/sample.db.

🔌 MCP客户端设置

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "data-analyst": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/MCP_Data_Analyst",
      "env": {
        "DATA_SOURCE": "data/sample.db"
      }
    }
  }
}

Gemini CLI

添加到您的 settings.json:

{
  "mcpServers": {
    "data-analyst": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/MCP_Data_Analyst"
    }
  }
}

🛠️ 可用工具

get_schema

获取数据库模式——列出所有表及其列和类型。首先调用此命令以了解可用的数据。

示例提示： *“数据库中有哪些表可用？”*

run_read_only_query

执行安全的SQL查询。结果以markdown表的形式返回（最多100行）。

示例提示： *“给我看看收入最高的5名员工”*

visualize_data

根据SQL查询结果生成图表。

参数：

• sql --SQL SELECT查询
• chart_type — bar, line, scatter, pie, hist
• x_column / y_column --轴列（如果省略，则自动检测）
• title --图表标题

示例提示： *“按地区创建总销售额条形图”*

📚 资源

data://schema

自动为LLM提供数据库模式（表、列、类型），以便它可以编写准确的查询而无需猜测。

📝 结构化日志记录

所有操作都会向stderr发送结构化JSON日志：

{"timestamp": "2026-02-21 12:00:00", "level": "INFO", "module": "src.db", "message": "db_initialized", "source": "data/sample.db", "type": ".db"}
{"timestamp": "2026-02-21 12:00:01", "level": "INFO", "module": "src.db", "message": "query_executed", "rows": 10, "elapsed_ms": 0.42}
{"timestamp": "2026-02-21 12:00:02", "level": "INFO", "module": "src.tools.visualize", "message": "chart_generated", "chart_type": "bar", "data_points": 4, "image_bytes": 12480}

日志事件包括：

• db_initialized --数据源路径和类型
• query_executed --行数和执行时间（ms）
• chart_generated --图表类型、数据点、图像大小
• query_rejected / query_error --查询被阻止或失败

🧪 测试

# Run full test suite (39 tests)
pytest tests/ -v --tb=short

🔄 CI/CD

GitHub操作管道(.github/workflows/ci.yml)每次推送/PR都会运行：

1. 棉绒 — flake8 + black --check
2. 测试 — pytest tests/ -v
3. Docker构建 --使用Buildx构建映像（无推送）