销售分析 MCP 服务器

一个自定义的 Model Context Protocol (MCP) 服务器，为 Claude Desktop 提供对实时销售数据库的直接、安全访问——将 Python 分析后端转变为任何兼容 MCP 的 AI 助手都可以使用的可复用工具，而无需为每个应用编写单独的集成。

什么是 MCP，以及为什么要为它构建服务器

Model Context Protocol 是一个开放标准（由 Anthropic 创建），它让 AI 助手能够通过通用接口连接到外部工具和数据源，而不是每个助手都需要为每个工具定制集成。编写 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 项目中相同的只读防护方法——这是一个很好的例子，说明为什么一次性精心构建该安全逻辑，在第二个独立工具中复用时能带来回报。

设置

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 提问，例如：

   “有哪些表可用，是否有我应该知道的销售异常？”

示例交互