Skip to main content
Glama
mcp-kpi-server

mcp-kpi-server

README.md
# mcp-kpi-server

[![CI](https://github.com/poojabhather99/mcp-kpi-server/actions/workflows/ci.yml/badge.svg)](https://github.com/poojabhather99/mcp-kpi-server/actions/workflows/ci.yml)

**Live demo (runs in your browser):** https://poojabhather99.github.io/mcp-kpi-server/

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an LLM client (Claude Desktop, Claude Code, or any MCP client) query an analytical database through a small set of safe, read-only tools.

The demo database is **synthetic** (health-worker visits across four districts, generated deterministically with a seed). No real data is included.

## Tools

| Tool | Purpose |
|---|---|
| `list_tables` | Tables available to query |
| `describe_table(table)` | Column names and types |
| `run_select(sql)` | Run one read-only SELECT (max 200 rows, flagged if truncated) |
| `get_kpi(name)` | Named KPIs: `completion_rate`, `avg_duration_min`, `visits_by_district` |

## Safety model

`run_select` accepts a single statement that starts with `SELECT` or `WITH` and contains none of the write/DDL/IO keywords (`insert`, `update`, `delete`, `drop`, `alter`, `create`, `attach`, `copy`, `pragma`, `call`, `install`, `load`, `export`, `set`). Multiple statements and unknown table names are rejected, and results are capped at 200 rows.

This is a keyword guard, not a sandbox. It will also reject a harmless query whose text contains one of those words, for example a column called `set`. For anything beyond a demo, run the server against a read-only database user or a read-only DuckDB file, and treat the guard as a second layer.

## Run

```bash
pip install -e ".[dev]"
mcp-kpi-server          # stdio transport
pytest -q               # 19 tests
```

Claude Desktop config:

```json
{
  "mcpServers": {
    "kpi": { "command": "mcp-kpi-server" }
  }
}
```

## Layout

- `src/mcpkpi/tools.py`: tool logic and the SQL guard, independent of MCP so it is unit tested directly
- `src/mcpkpi/server.py`: thin FastMCP wrapper registering the four tools
- `src/mcpkpi/db.py`: seeded demo dataset
- `tests/`: guard cases, row cap, JSON-safe dates, KPI checks, tool registration

## Limitations

- Pinned to `mcp<2` (the v1 `FastMCP` API); v2 renamed it.
- Demo data only; swapping in a real database means replacing `db.py` and the `KPIS` queries.
- Tested through the tool layer and tool registration, not against a live MCP client session.

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool occupies a clearly distinct role: listing tables, describing a table, running an arbitrary read-only query, and fetching a named KPI. The only potential overlap is get_kpi vs run_select, but the descriptions make it clear one is a curated convenience wrapper and the other is generic SQL.

Naming Consistency5/5

All four tools follow a consistent snake_case verb_noun pattern (list_tables, describe_table, run_select, get_kpi). Verb choice matches the action type well (list vs describe vs run vs get).

Tool Count5/5

Four tools is proportionate to a narrow read-only KPI/query server; each tool covers a distinct stage of the workflow (discover schema, inspect schema, ad-hoc query, curated KPI). Nothing feels redundant or missing at the count level.

Completeness4/5

The surface covers schema discovery, inspection, ad-hoc reads, and predefined KPIs, which is solid for a read-only server. Minor gaps: no tool to enumerate available KPI names (agents must parse descriptions) and the 200-row cap has no pagination or export path, which could dead-end on larger results.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues