<div align="center">

analytics-mcp

Production-grade MCP server for enterprise sales analytics. 6 tools, 3 resources, 2 prompts — all with structured outputs — over a SQLite database. Connects to Claude, OpenCode, Cursor, and any MCP client.

</div>

---

What This Is

A Model Context Protocol (MCP) server that exposes an enterprise sales database to LLM clients. Instead of copy-pasting data into ChatGPT, connect this server and let the AI query, analyze, and visualize your data through structured tools.

Built with the latest MCP patterns (July 2026):

• FastMCP 3.4 — high-level server framework
• Structured outputs — Pydantic models define outputSchema for every tool
• Tool annotations — readOnlyHint lets clients skip confirmations
• In-memory client testing — no port flakiness, era-neutral
• Resources — schema introspection, table details, report templates
• Prompts — reusable analysis templates (sales analysis, customer segmentation)
• Both transports — stdio (local) + HTTP (remote)

---

Quick Start

git clone https://github.com/bhavya998/analytics-mcp.git
cd analytics-mcp
uv sync

# Initialize database (200 customers, 25 products, 2000 orders)
uv run analytics-mcp init

# Start server (stdio for local MCP clients)
uv run analytics-mcp serve

# Or HTTP transport for remote access
uv run analytics-mcp serve --transport http --port 8000

Connect to Claude Desktop / OpenCode

Add to your MCP client config:

{
  "mcpServers": {
    "analytics": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/analytics-mcp", "analytics-mcp", "serve"]
    }
  }
}

Then ask: "Show me the top 5 products by revenue and analyze the monthly sales trend"

---

Tools

Tool	Description	Annotations
query_database	Run parameterized SELECT queries against the database	readOnlyHint
get_revenue_report	Revenue by category/region/tier/status/month with profit analysis	readOnlyHint
get_customer_profile	360-degree customer view: orders, LTV, favorite category, recent activity	readOnlyHint
get_top_products	Leaderboard by revenue or quantity, optional category filter	readOnlyHint
analyze_sales_trend	Time-series with period-over-period growth rates	readOnlyHint
get_regional_performance	Ranked regional performance with revenue, orders, customers, AOV	readOnlyHint

Resources

URI	Description
schema://database	Full database schema (all tables, columns, types, row counts)
schema://tables/{table_name}	Detailed table schema with sample rows
report://templates	Available report templates and usage examples

Prompts

Prompt	Description
sales_analysis	Comprehensive sales analysis with focus area (overall/category/region/customer)
customer_segmentation	Segment customers into Champions/At Risk/New/Dormant with retention strategies

---

Database Schema

customers (200 rows)
  id, name, email, company, region, tier, signup_date, lifetime_value

products (25 rows)
  id, name, category, price, cost, stock

orders (2000 rows)
  id, customer_id, employee_id, order_date, status, total

order_items (5000+ rows)
  id, order_id, product_id, quantity, unit_price

employees (15 rows)
  id, name, role, region, hire_date

---

Testing

make test         # 43 tests: database, tools, full MCP client integration
make lint         # ruff

Suite	Tests	Pattern
test_database.py	8	DB init, query validation, schema introspection
test_tools.py	17	Direct tool function calls (all 6 tools)
test_server_client.py	12	Full MCP protocol via in-memory Client

Tests use the modern in-memory Client(mcp) pattern — no ports, no subprocesses, era-neutral.

---

Tech Stack

Layer	Technology
MCP Framework	FastMCP 3.4 (Prefect)
Protocol	MCP 1.28 (Streamable HTTP + stdio)
Database	SQLite with seeded enterprise data
Validation	Pydantic v2 (structured tool outputs)
CLI	Typer + Rich
Testing	pytest + pytest-asyncio + FastMCP Client

Project Structure

analytics-mcp/
├── src/analytics_mcp/
│   ├── server.py         MCP server: 6 tools, 3 resources, 2 prompts
│   ├── database.py       SQLite setup + schema + seed data (2000+ orders)
│   ├── schemas.py        Pydantic models for structured outputs
│   └── cli.py            CLI (serve, init, inspect)
├── tests/                43 tests (database, tools, client integration)
├── data/                 SQLite database (auto-generated, gitignored)
├── Makefile
└── pyproject.toml

License

MIT