Sales Analytics MCP Server

A custom Model Context Protocol (MCP) server that gives Claude Desktop direct, safe access to a live sales database — turning a Python analytics backend into a reusable tool any MCP-compatible AI assistant can use, without writing a single integration per application.

What is MCP, and why build a server for it

Model Context Protocol is an open standard (created by Anthropic) that lets AI assistants connect to external tools and data sources through a common interface, instead of every assistant needing a custom-built integration for every tool. Writing an MCP server means building the connection once, per data source — and any MCP-compatible client (Claude Desktop, Claude Code, or other MCP-aware applications) can use it immediately, with no per-application rework.

This project exposes a real PostgreSQL sales database (the same one used in ai-analytics-agent) as a set of MCP tools, so Claude can query it, inspect its schema, and run anomaly detection — directly inside a normal conversation.

Related MCP server: pg-mcp

Architecture

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

Tools exposed

Tech Stack

Engineering notes

• Caught a breaking SDK change mid-development: the MCP Python SDK shipped a major version (2.0.0) that renamed FastMCP to MCPServer and moved its import path, right as this project was being built. The server was updated to the new API rather than pinning an older version, so the code reflects the current SDK surface.

• Claude chooses its own tool strategy: when asked to find anomalies before find_sales_anomalies existed, Claude independently used run_sql_query to investigate — checking for duplicate rows, negative amounts, and per-category breakdowns on its own initiative, arriving at the same root cause the dedicated tool later confirmed. This is a useful illustration of how an LLM client actually chooses between a general-purpose tool and a specialized one, rather than always preferring the "obvious" dedicated function.

• Same safety model as the Text-to-SQL agent: run_sql_query reuses the same read-only guardrail approach as the Python-based Text-to-SQL project — a good example of why building that safety logic once, carefully, pays off when it's reused in a second, independent tool.

Setup

1. Install dependencies: pip install -r requirements.txt

2. Create a .env file with: DATABASE_URL=your_postgresql_connection_string

3. Add the server to Claude Desktop's config file (claude_desktop_config.json):

   {
     "mcpServers": {
       "sales-analytics": {
         "command": "python",
         "args": ["/full/path/to/server.py"]
       }
     }
   }

4. Fully restart Claude Desktop (quit via Task Manager / Activity Monitor, not just closing the window)

5. Start a new chat and ask Claude something like:

   "What tables are available, and are there any sales anomalies I should know about?"

Example interaction