AI导哈

数据分析MCP服务器

一个将LLM转化为数据分析师的MCP服务器，支持数据库连接、自然语言查询SQL和可视化数据。

  • by anestisal10
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 anestisal10/mcp-data-analyst

使用说明

📊 数据分析MCP服务器

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

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

🏗️ 建筑

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

    Client <-->|"MCP Protocol<br/>(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

✨ 特性

特性 描述
🗄️ 多源 SQLite数据库、CSV文件、Excel文件
🔒 只读安全 只读 SELECT 允许查询--不允许意外修改数据
📋 架构作为资源 LLM会自动看到表结构
📊 可视化 条形图、折线图、散点图、饼图和直方图
📈 统计 每次可视化时自动汇总统计
📝 结构化日志 每个操作的JSON格式日志
🐳 Docker 一个命令设置 docker-compose
✅ CI/CD GitHub操作（lint+test+Docker构建）

📁 项目结构

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 指向数据文件的环境变量：

文件类型 扩展名 注释
SQLite .db, .sqlite, .sqlite3 直接连接
CSV .csv 加载到内存SQLite中
Excel .xlsx, .xls 每张纸都变成了一张桌子

如果 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构建映像（无推送）

相关 MCP