Sales Analytics MCP Server

Un servidor Model Context Protocol (MCP) personalizado que ofrece a Claude Desktop acceso directo y seguro a una base de datos de ventas en directo, convirtiendo un backend de análisis de Python en una herramienta reutilizable que cualquier asistente de IA compatible con MCP puede usar, sin escribir una sola integración por aplicación.

Qué es MCP y por qué crear un servidor para ello

Model Context Protocol es un estándar abierto (creado por Anthropic) que permite a los asistentes de IA conectarse a herramientas externas y fuentes de datos a través de una interfaz común, en lugar de que cada asistente necesite una integración personalizada para cada herramienta. Escribir un servidor MCP significa construir la conexión una sola vez, por fuente de datos, y cualquier cliente compatible con MCP (Claude Desktop, Claude Code u otras aplicaciones compatibles con MCP) puede usarlo de inmediato, sin necesidad de rehacer nada por aplicación.

Este proyecto expone una base de datos de ventas real de PostgreSQL (la misma utilizada en ai-analytics-agent) como un conjunto de herramientas MCP, de modo que Claude puede consultarla, inspeccionar su esquema y ejecutar detección de anomalías, directamente dentro de una conversación normal.

Related MCP server: pg-mcp

Arquitectura

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

Herramientas expuestas

Stack tecnológico

Notas de ingeniería

• Detecté un cambio disruptivo del SDK a mitad del desarrollo: el SDK de Python de MCP lanzó una versión mayor (2.0.0) que renombró FastMCP a MCPServer y movió su ruta de importación, justo cuando se estaba construyendo este proyecto. El servidor se actualizó a la nueva API en lugar de fijar una versión anterior, por lo que el código refleja la superficie actual del SDK.

• Claude elige su propia estrategia de herramientas: cuando se le pidió encontrar anomalías antes de que existiera find_sales_anomalies, Claude usó run_sql_query de forma independiente para investigar, comprobando filas duplicadas, importes negativos y desgloses por categoría por iniciativa propia, llegando a la misma causa raíz que la herramienta dedicada confirmó más tarde. Es una ilustración útil de cómo un cliente LLM elige realmente entre una herramienta de propósito general y una especializada, en lugar de preferir siempre la función dedicada "obvia".

• El mismo modelo de seguridad que el agente Text-to-SQL: run_sql_query reutiliza el mismo enfoque de protección de solo lectura que el proyecto Text-to-SQL basado en Python, un buen ejemplo de por qué construir esa lógica de seguridad una sola vez, con cuidado, da sus frutos cuando se reutiliza en una segunda herramienta independiente.

Configuración

1. Instala las dependencias: pip install -r requirements.txt

2. Crea un archivo .env con: DATABASE_URL=your_postgresql_connection_string

3. Añade el servidor al archivo de configuración de Claude Desktop (claude_desktop_config.json):

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

4. Reinicia Claude Desktop por completo (sal de la aplicación mediante el Administrador de tareas / Monitor de actividad, no solo cerrando la ventana)

5. Inicia un nuevo chat y pregúntale a Claude algo como:

   "¿Qué tablas hay disponibles y hay alguna anomalía de ventas que deba conocer?"

Ejemplo de interacción