使用说明

🔍 MCP数据镜头

强大的FastMCP服务器，用于MySQL数据库分析，具有SSH隧道支持、数据可视化和AI驱动的洞察力。

✨ 特性

🔐 安全数据库访问

SSH隧道支持：通过SSH隧道安全连接到远程MySQL数据库
只读执行：内置查询验证确保只执行SELECT、SHOW、DESCRIBE和EXPLAIN查询
连接池：高效的数据库连接管理，实现最佳性能

📊 数据分析和可视化

SQL查询执行：执行具有结构化结果的只读查询
架构检查：探索数据库表、列、索引和统计信息
数据可视化：直接从查询结果创建漂亮的图表（条形图、折线图、饼图、散点图）
报告生成：人工智能辅助的综合数据分析报告

🛠️ MCP协议特性

工具：执行查询、检查模式和创建可视化
资源：通过URI公开数据库信息
提示：用于生成报告和查询的预构建模板
中间件：基于标签的访问控制，增强安全性

🚀 灵活部署

标准模式：与Claude Desktop的原生集成
HTTP模式：用于web应用程序和其他客户端的REST API
OAuth身份验证：Google OAuth 2.0支持安全访问
模块化架构：干净、可维护的代码结构

🚀 安装

先决条件

Python 3.11或更高版本
MySQL数据库（本地或远程）
SSH访问数据库服务器（如果使用SSH隧道）
紫外线包管理器

安装步骤

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/yourusername/mcp-data-lens.git
cd mcp-data-lens

# Quick setup with Makefile (recommended)
make setup

# Or install dependencies manually with uv (uses uv.lock)
uv sync

# Or create a virtual environment and install manually
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Makefile快速入门

该项目包括一个用于常见任务的全面Makefile：

# See all available commands
make help

# Complete setup (install deps + create .env)
make setup

# Run in stdio mode (Claude Desktop)
make run-stdio

# Run in HTTP mode
make run-http

# Run tests
make test

# Format and lint code
make fix

# Run all checks
make check

⚙️ 配置

环境变量

创建 .env 项目根目录中的文件：

# Transport Mode
TRANSPORT_MODE=stdio  # or "http"

# SSH Tunnel Configuration (optional)
USE_SSH_TUNNEL=true
SSH_HOST=your-ssh-server.com
SSH_PORT=22
SSH_USER=your-username
SSH_KEY_PATH=~/.ssh/id_rsa  # or use SSH_PASSWORD
# SSH_PASSWORD=your-password  # Alternative to key-based auth

# Database Configuration
DB_HOST=localhost  # or remote host if not using SSH tunnel
DB_PORT=3306
DB_USER=your-db-user
DB_PASSWORD=your-db-password
DB_NAME=your-database-name

# SSH Tunnel Local Binding (if using SSH tunnel)
LOCAL_BIND_PORT=3306

# HTTP Server Configuration (if TRANSPORT_MODE=http)
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# OAuth Authentication (Google)
AUTH_ENABLED=false
AUTH_SECRET_KEY=change-me-in-production
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

配置选项说明

变量	描述	默认值
`TRANSPORT_MODE`	服务器模式： `stdio` 对于克劳德桌面， `http` 用于REST API	`stdio`
`USE_SSH_TUNNEL`	为数据库连接启用SSH隧道	`true`
`SSH_HOST`	SSH服务器主机名	-
`SSH_PORT`	SSH服务器端口	`22`
`SSH_USER`	SSH用户名	-
`SSH_KEY_PATH`	SSH私钥的路径	`~/.ssh/id_rsa`
`SSH_PASSWORD`	SSH密码（密钥的替代）	-
`DB_HOST`	MySQL主机（如果使用SSH隧道，则为localhost）	`localhost`
`DB_PORT`	MySQL端口	`3306`
`DB_USER`	MySQL用户名	`root`
`DB_PASSWORD`	MySQL密码	-
`DB_NAME`	MySQL数据库名称	-
`LOCAL_BIND_PORT`	SSH隧道的本地端口	`3306`
`SERVER_HOST`	HTTP服务器绑定地址	`0.0.0.0`
`SERVER_PORT`	HTTP服务器端口	`8000`
`AUTH_ENABLED`	启用OAuth身份验证	`false`
`GOOGLE_CLIENT_ID`	谷歌OAuth 2.0客户端ID	-
`GOOGLE_CLIENT_SECRET`	谷歌OAuth 2.0客户端密码	-

OAuth身份验证设置

MCP Data Lens支持使用Google作为身份提供者的OAuth 2.0身份验证。这是可选的，但建议用于生产部署。

设置Google OAuth

创建谷歌云项目:
- 首选谷歌云控制台
- 创建新项目或选择现有项目
启用Google OAuth API:
- 导航到“API和服务”→ “凭据”
- 点击“创建凭据”→ “OAuth客户端ID”
- 如果您还没有配置OAuth同意屏幕
配置OAuth客户端:
- 应用程序类型：“Web应用程序”
- 授权重定向URI：添加 http://localhost:8000/auth/callback （根据需要调整主机/端口）
- 复制客户端ID和客户端密码

更新环境变量:

AUTH_ENABLED=true
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

以HTTP模式启动服务器:

export TRANSPORT_MODE=http
make run-http

OAuth流

启用OAuth后，服务器会公开以下端点：

/.well-known/oauth-authorization-servers -OAuth服务器元数据
/authorize -启动OAuth流
/auth/callback -处理来自Google的OAuth回调

身份验证流程：

客户端通过访问启动登录 /authorize
用户被重定向到谷歌进行身份验证
成功验证后，Google重定向回 /auth/callback
服务器验证令牌并创建经过身份验证的会话
后续MCP请求包括身份验证标头

📖 用法

使用克劳德桌面

配置Claude桌面：添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "data-lens": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-data-lens",
        "run",
        "--with",
        "fastmcp",
        "--with",
        "mysql-connector-python",
        "--with",
        "matplotlib",
        "--with",
        "pandas",
        "--with",
        "paramiko==3.5.1",
        "--with",
        "sshtunnel",
        "--with",
        "uvicorn",
        "server.py",
      ],
      "env": {
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}

重新启动克劳德桌面
开始使用工具:
- 让Claude“列出数据库中的所有表”
- 请求“按类别显示销售柱状图”
- 使用“为用户表创建综合报告”生成报告

Claude MCP服务器

Claude MCP工具

Claude MCP查询

Claude MCP执行

带光标

Cursor支持基于HTTP的MCP服务器，使集成变得简单。

以HTTP模式启动MCP服务器:

# Set environment to HTTP mode
export TRANSPORT_MODE=http

# Run the server
make run-http
# Or manually: uv run server.py

服务器将在以下时间启动 http://localhost:8000

配置光标：添加到光标设置（光标设置→ 特性→ MCP):

{
  "mcpServers": {
    "data-lens": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

开始使用工具：Cursor将立即检测到MCP服务器并显示所有可用工具。您现在可以：
- 要求Cursor“列出数据库中的所有表”
- 请求“按类别显示销售柱状图”
- 使用“为用户表创建综合报告”生成报告
- 在编码工作流程中直接使用MCP工具

注：在Cursor中使用MCP工具之前，请确保HTTP服务器正在运行。您可以在后台或单独的终端中运行它。

作为HTTP服务器

# Set environment
export TRANSPORT_MODE=http
# Or with uv
uv run server.py

服务器将在以下时间启动 http://localhost:8000 （或您配置的主机/端口）。

访问MCP端点: http://localhost:8000/mcp

🛠️ 可用工具

1. `execute_query`

使用结构化结果执行只读SQL查询。

参数：

query （string）：要执行的SQL查询（仅限SELECT、SHOW、DESCRIBE、EXPLAIN）

退货：

{
  "success": true,
  "columns": ["id", "name", "email"],
  "rows": [
    {"id": 1, "name": "John Doe", "email": "john@example.com"},
    {"id": 2, "name": "Jane Smith", "email": "jane@example.com"}
  ],
  "row_count": 2
}

例子：

SELECT id, name, email FROM users WHERE status = 'active' LIMIT 10

2. `list_tables`

列出连接数据库中的所有表。

退货：

{
  "success": true,
  "tables": ["users", "orders", "products"],
  "count": 3
}

3. `get_table_schema`

获取特定表的详细架构信息。

参数：

table_name （string）：要检查的表的名称

退货：

{
  "success": true,
  "table_name": "users",
  "columns": [
    {
      "Field": "id",
      "Type": "int",
      "Null": "NO",
      "Key": "PRI",
      "Default": null,
      "Extra": "auto_increment"
    }
  ],
  "indexes": [...],
  "row_count": 1000
}

4. `plot_graph`

根据查询结果创建数据可视化。

参数：

query （字符串）：SQL SELECT查询
chart_type （字符串）：图表类型- bar, line, pie，或 scatter
x_column （string）：x轴的列名
y_column （string）：y轴的列名
title （字符串，可选）：图表标题

退货： 图表的PNG图像

例子：

query = "SELECT category, SUM(sales) as total FROM products GROUP BY category"
chart_type = "bar"
x_column = "category"
y_column = "total"
title = "Sales by Category"

5. `collect_user_info`

演示MCP启发能力的交互式工具。该工具通过交互式提示收集用户信息，展示MCP服务器如何向用户请求结构化数据。

目的：

演示 ctx.elicit() 上下文方法
演示如何处理用户响应（接受、拒绝、取消）
使用Pydantic模型收集结构化数据的示例

它是如何工作的：

展示一个交互式表单，要求填写姓名和年龄
用户可以接受、拒绝或取消请求
根据用户的操作返回个性化消息

退货：

如果接受： "Hello {name}, you are {age} years old"
如果拒绝： "Information not provided"
如果取消： "Operation cancelled"

使用案例：

交互式数据收集工作流程
用户偏好收集
运行时的动态配置

6. `process_data`

使用实时进度报告处理来自资源的数据。此工具演示了MCP的进度跟踪功能和资源读取。

参数：

data_uri （string）：要处理的资源的URI（例如。， mysql://schema/database)

目的：

演示 ctx.report_progress() 上下文方法
演示如何使用以编程方式读取资源 ctx.read_resource()
使用示例 ctx.sample() 利用客户的LLM进行数据分析
说明正确的信息/错误记录 ctx.info() 和 ctx.error()

它是如何工作的：

从指定的资源URI读取数据
报告进度为50%
尝试使用客户端的LLM生成数据的AI摘要
如果LLM不可用，则返回到简单预览
报告100%完成
返回具有数据长度、摘要和预览的结构化响应

退货：

{
  "length": 1024,
  "summary": "Database schema with 15 tables including users, orders...",
  "preview": "Database: myapp_production\nMySQL Version: 8.0.35..."
}

使用案例：

长时间运行的数据处理任务
资源分析与总结
向用户展示进度反馈
具有状态更新的多步工作流

📚 资源

资源通过URI公开数据库信息。

`mysql://schema/database`

获取全面的数据库信息，包括：

数据库名称和MySQL版本
连接类型（SSH隧道或直接）
包含统计信息（行数、大小、引擎）的所有表的列表

输出示例：

Database: myapp_production
MySQL Version: 8.0.35
Connection: SSH Tunnel
Total Tables: 15

Tables:
Table                          Rows      Size (MB) Engine     Collation
------------------------------------------------------------------------------------------
users                        10,523        12.45    InnoDB     utf8mb4_unicode_ci
orders                       45,892        67.23    InnoDB     utf8mb4_unicode_ci
products                      2,341         8.91    InnoDB     utf8mb4_unicode_ci

💡 提示

用于人工智能辅助分析的预构建提示模板。

1. `generate_report`

生成全面的数据分析报告。

参数：

table_name （string）：要分析的表
metrics （string）：要关注的具体指标（默认值：“all”）

生成：

执行摘要
数据分布分析
关键见解和趋势
可采取行动的建议

2. `query_builder`

为常见任务生成优化的SQL查询。

参数：

table_name （string）：要查询的表
task （string）：任务类型- explore, aggregate, trend，或 compare
conditions （字符串，可选）：WHERE子句条件

生成： 使用最佳实践优化SQL查询

🏗️ 建筑

项目结构

mcp-data-lens/
├── data_lens/
│   ├── config/
│   │   ├── __init__.py
│   │   └── settings.py          # Configuration management
│   ├── database/
│   │   ├── __init__.py
│   │   ├── connection.py        # Database connection & pooling
│   │   └── utils.py             # Query validation utilities
│   ├── mcp/
│   │   ├── __init__.py
│   │   ├── mcp.py               # Main MCP instance
│   │   ├── middleware/
│   │   │   ├── __init__.py
│   │   │   └── tag_middleware.py  # Access control middleware
│   │   ├── prompts/
│   │   │   ├── __init__.py
│   │   │   └── report_prompts.py  # Report & query prompts
│   │   ├── resources/
│   │   │   ├── __init__.py
│   │   │   └── database_resources.py  # Database info resources
│   │   └── tools/
│   │       ├── __init__.py
│   │       ├── elicit.py        # User info elicitation
│   │       ├── mysql.py         # MySQL query tools
│   │       ├── progress_tool.py # Progress tracking
│   │       └── visualization.py # Chart generation
│   └── utils/
│       ├── __init__.py
│       └── logger.py            # Logging configuration
├── server.py                    # Main entry point
├── pyproject.toml              # Project dependencies
└── README.md                   # This file

关键组件

1. 数据库层 (`data_lens/database/`)

connection.py：使用SSH隧道支持管理MySQL连接
连接池提高性能
关机时自动清理

2. MCP层 (`data_lens/mcp/`)

工具：执行查询、检查模式、创建可视化
资源：通过URI公开数据库信息
提示：用于报告和查询的预构建模板
中间件：基于标签的访问控制

3. 配置 (`data_lens/config/`)

使用Pydantic进行基于环境的配置
支持SSH和数据库设置
灵活的传输模式（stdio/HTTP）

4. 公用事业 (`data_lens/utils/`)

带颜色编码输出的结构化日志记录
查询验证助手

数据流

Client (Claude Desktop / HTTP)
    ↓
MCP Server (FastMCP)
    ↓
Middleware (Access Control)
    ↓
Tools/Resources/Prompts
    ↓
Database Layer (Connection Pool)
    ↓
SSH Tunnel (optional)
    ↓
MySQL Database

🔧 发展

使用Makefile

该项目包括一个全面的Makefile，其中包含所有常见的开发任务：

# Display all available commands
make help

# Setup and Installation
make install          # Install production dependencies
make dev              # Install all dependencies including dev tools
make setup            # Complete setup (deps + .env)

# Running the Server
make run-stdio        # Run in stdio mode (Claude Desktop)
make run-http         # Run in HTTP mode
make run              # Alias for run-stdio

# Testing
make test             # Run tests
make test-cov         # Run tests with coverage report
make test-verbose     # Run tests with verbose output

# Code Quality
make lint             # Run linting checks
make lint-fix         # Run linting with auto-fix
make format           # Format code (black + isort)
make format-check     # Check formatting without changes
make type-check       # Run mypy type checking
make check            # Run all checks (lint + format + type)
make fix              # Fix linting and format code

# Database
make docker-db        # Start MySQL test database
make docker-db-stop   # Stop and remove test database
make docker-db-logs   # View database logs

# Cleanup
make clean            # Remove cache and build artifacts
make clean-all        # Remove everything including venv

# Utilities
make info             # Display project information
make version          # Show version
make update           # Update dependencies
make lock             # Update lock file

# All-in-One
make all              # Clean + install + check + test
make ci               # Run CI checks
make pre-commit       # Run pre-commit checks

手动命令（不带Makefile）

如果您不想使用Make：

# Run tests
uv run pytest
uv run pytest --cov=data_lens --cov-report=html

# Code quality
uv run ruff check data_lens/
uv run black data_lens/
uv run mypy data_lens/

添加新工具

在中创建新文件 data_lens/mcp/tools/
定义注册功能：

from fastmcp import FastMCP, Context

def register_my_tools(mcp: FastMCP):
    @mcp.tool(
        name="my_tool",
        description="What my tool does",
        tags={"category"},
        meta={"version": "1.0"}
    )
    async def my_tool(param: str, ctx: Context) -> dict:
        # Your tool logic here
        return {"result": "success"}

注册于 data_lens/mcp/mcp.py:

from data_lens.mcp.tools import register_my_tools
register_my_tools(mcp)

添加新资源

类似的模式 data_lens/mcp/resources/:

def register_my_resources(mcp: FastMCP):
    @mcp.resource(
        uri="custom://my-resource",
        name="My Resource",
        description="Resource description",
        mime_type="text/plain"
    )
    async def my_resource(ctx: Context) -> str:
        return "Resource content"

MCP检验员测试

FastMCP包括一个内置的开发检查器，可帮助您在开发过程中测试和调试MCP服务器。

使用MCP检查器运行

用服务器启动检查器:

# Run the FastMCP dev inspector
fastmcp dev server.py

检查员将：
- 启动web界面（通常在 http://localhost:5173)
- 以stdio模式连接到MCP服务器
- 如果尚未读取，则需要将传输类型更改为流式http
- 将url更改为http://localhost:8000/mcp
- 点击连接
- 显示所有可用的工具、资源和提示
- 允许您以交互方式测试工具调用
使用检查器界面：
- 工具选项卡：查看所有可用工具及其模式，使用自定义参数测试工具调用
- 资源选项卡：浏览可用资源并查看其内容
- 提示选项卡：检查提示模板并使用参数对其进行测试
- 察看连接信息：查看服务器元数据和功能

📝 例子

示例1：基本查询执行

用户： “按订单总价值显示前10名客户”

克劳德使用：

SELECT 
    c.name,
    c.email,
    COUNT(o.id) as total_orders,
    SUM(o.total_amount) as total_value
FROM customers c
JOIN orders o ON c.id = o.customer_id
GROUP BY c.id, c.name, c.email
ORDER BY total_value DESC
LIMIT 10

示例2：数据可视化

用户： “创建一个折线图，显示2024年的月度收入趋势”

克劳德：

执行查询以获取每月收入
呼叫 plot_graph 与：
- chart_type：“线”
- x_列：“月”
- y_column:“收入”
- 标题：“2024年月度收入趋势”
返回漂亮的折线图图像

示例3：综合报告

用户： “为订单表生成综合报告”

克劳德：

用途 generate_report 提示
呼叫 get_table_schema 理解结构
执行多个查询以进行分析
创建可视化
生成具有洞察力的详细报告

🐛 故障排除

SSH连接问题

问题： 无法通过SSH隧道连接

解决：

验证SSH凭据和密钥权限： chmod 600 ~/.ssh/id_rsa
手动测试SSH连接： ssh -i ~/.ssh/id_rsa user@host
检查SSH服务器上的防火墙规则
确保MySQL正在远程服务器上的localhost上侦听

数据库连接问题

问题： MySQL连接失败

解决：

验证MySQL凭据
检查MySQL服务器是否正在运行
确保数据库名称存在
验证用户是否具有适当的权限
检查MySQL日志以了解详细错误

端口冲突

问题： “地址已在使用中”错误

解决：

改变 LOCAL_BIND_PORT 在 .env
使用端口终止进程： lsof -ti:3306 | xargs kill -9

查询执行错误

问题： “只允许只读查询”

解决方案： 仅使用SELECT、SHOW、DESCRIBE或EXPLAIN语句

Claude桌面集成

问题： 服务器未显示在Claude Desktop中

解决：

验证 claude_desktop_config.json 语法
检查配置中的绝对路径
完全重新启动克劳德桌面
在Claude Desktop中检查日志：帮助→ 查看日志

🤝 贡献

欢迎投稿！请按照以下步骤操作：

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
进行更改
运行测试和梳理
提交您的更改： git commit -m 'Add amazing feature'
推到分支： git push origin feature/amazing-feature
打开拉取请求

开发指南

遵循PEP 8风格指南
为新功能添加测试
根据需要更新文档
对所有函数使用类型提示
将文档字符串添加到所有公共函数中

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

FastMCP -现代MCP服务器框架
Anthropic -对于Claude和MCP协议
本项目的所有贡献者和用户

📞 支持

问题: GitHub问题
讨论: GitHub讨论

内置于❤️ 使用 FastMCP

使用说明

🔍 MCP数据镜头

✨ 特性

🔐 安全数据库访问

📊 数据分析和可视化

🛠️ MCP协议特性

🚀 灵活部署

📋 目录

🚀 安装

先决条件

安装步骤

Makefile快速入门

⚙️ 配置

环境变量

配置选项说明

OAuth身份验证设置

设置Google OAuth

OAuth流

📖 用法

使用克劳德桌面

Claude MCP服务器

Claude MCP工具

Claude MCP查询

Claude MCP执行

带光标

作为HTTP服务器

🛠️ 可用工具

1. execute_query

2. list_tables

3. get_table_schema

4. plot_graph

5. collect_user_info

6. process_data

📚 资源

mysql://schema/database

💡 提示

1. generate_report

2. query_builder

🏗️ 建筑

项目结构

关键组件

1. 数据库层 (data_lens/database/)

2. MCP层 (data_lens/mcp/)

3. 配置 (data_lens/config/)

4. 公用事业 (data_lens/utils/)

数据流

🔧 发展

使用Makefile

手动命令（不带Makefile）

添加新工具

添加新资源

MCP检验员测试

使用MCP检查器运行

📝 例子

示例1：基本查询执行

示例2：数据可视化

示例3：综合报告

🐛 故障排除

SSH连接问题

数据库连接问题

端口冲突

查询执行错误

Claude桌面集成

🤝 贡献

开发指南

📄 许可证

🙏 致谢

📞 支持

相关 MCP

图表生成MCP服务器

开发者辅助工具

ECharts 图表生成 MCP 服务

图表生成服务

Excel文件管理分析服务

GSAP动画生成工具

1. `execute_query`

2. `list_tables`

3. `get_table_schema`

4. `plot_graph`

5. `collect_user_info`

6. `process_data`

`mysql://schema/database`

1. `generate_report`

2. `query_builder`

1. 数据库层 (`data_lens/database/`)

2. MCP层 (`data_lens/mcp/`)

3. 配置 (`data_lens/config/`)

4. 公用事业 (`data_lens/utils/`)