Skip to main content
Glama
mcp-kpi-server

mcp-kpi-server

mcp-kpi-server

CI

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

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

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 tests

Claude 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 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.

Available Tools

4 tools
describe_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

    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

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      6
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients and LLMs to interact with a DuckDB database through SQL query execution, table creation, and schema inspection, with optional read-only operation.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -