mcp-kpi-server
Allows querying a DuckDB analytical database through safe, read-only tools: listing available tables, describing table columns and types, running a single SELECT/WITH query with a 200-row cap, and retrieving named KPIs such as completion rate, average duration, and visits by district.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-kpi-server Show me visits by district KPI."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-kpi-server
Live demo (runs in your browser): https://poojabhather99.github.io/mcp-kpi-server/
A Model Context Protocol 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 |
| Tables available to query |
| Column names and types |
| Run one read-only SELECT (max 200 rows, flagged if truncated) |
| Named KPIs: |
Related MCP server: mcp-server-duckdb
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
pip install -e ".[dev]"
mcp-kpi-server # stdio transport
pytest -q # 19 testsClaude Desktop config:
{
"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 directlysrc/mcpkpi/server.py: thin FastMCP wrapper registering the four toolssrc/mcpkpi/db.py: seeded demo datasettests/: guard cases, row cap, JSON-safe dates, KPI checks, tool registration
Limitations
Pinned to
mcp<2(the v1FastMCPAPI); v2 renamed it.Demo data only; swapping in a real database means replacing
db.pyand theKPISqueries.Tested through the tool layer and tool registration, not against a live MCP client session.
Available Tools
4 toolsdescribe_tableB
Return column names and types for a table.
Inputs: table (required). Returns: result
get_kpiB
Compute a named KPI: completion_rate, avg_duration_min or visits_by_district.
Inputs: name (required).
list_tablesA
List the tables available to query.
Inputs: no named parameters. Returns: result
run_selectA
Run a single read-only SELECT query (max 200 rows returned).
Inputs: sql (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
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.
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).
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.
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
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
The grounded data layer for any LLM: governed SQL, metrics, lineage and catalog over your data.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to discover and execute analytical queries on a DuckDB dataset through typed MCP tools, with guarded read-only SQL support for complex calculations without direct database access.6MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients and LLMs to interact with a DuckDB database through SQL query execution, table creation, and schema inspection, with optional read-only operation.-
- FlicenseNot gradedqualityAmaintenanceEnables LLMs to interact with a local DuckDB database through a single unified SQL query tool, supporting operations such as querying, table creation, joins, and schema inspection. Optional read-only mode enforces native write protection so data can be analyzed safely without unintended changes.-
- FlicenseNot gradedqualityAmaintenanceEnables LLMs to interact with a DuckDB database by executing arbitrary SQL through a single unified query tool, supporting operations such as querying, table creation, and schema inspection. Supports a read-only mode that enforces DuckDB's native protection to prevent any writes.-