Skip to main content
Glama
Sign In
deenesjakoruzh
db-mcp

db-mcp

by denezhkinia
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

db-mcp

A read-only MCP server that gives an AI agent safe access to a small SQLite shop database (shop.db): schema discovery, free-form read-only SQL, and pre-built analytics reports.

Install

npm install

Related MCP server: shop-db

Configure

The server reads SHOP_DB_PATH from the process environment to locate the database file. It is optional — if unset, the server uses shop.db in the project root. .env files are not read automatically (there is no dotenv dependency and no --env-file flag in package.json's scripts); .env.example is provided only as a reminder of the variable name. Set SHOP_DB_PATH in the actual environment the server runs in — for a stdio MCP client, that means the env key of its config (see "Connect a client" below).

Build

npm run build

Run

npm start
# or directly:
node dist/index.js

The server speaks MCP over stdio — it expects to be launched as a child process by an MCP client/host, not run interactively.

Connect a client

Generic stdio MCP client config:

{
  "mcpServers": {
    "db-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/db-mcp/dist/index.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/shop.db" }
    }
  }
}

Claude Desktop: add the same block under mcpServers in claude_desktop_config.json (see MCP.md for the per-OS config file location), then restart Claude Desktop.

Tools

Tool

Description

list_tables

List all tables with a short description and row count. Call this first.

describe_table

Column definitions, keys, row count, and sample rows for one table (customers, products, orders, order_items).

query

Run a single read-only SELECT (or WITH ... SELECT) with limit/offset pagination.

get_top_customers

Top customers by total spending or order count. Excludes cancelled orders.

get_top_products

Best-selling products by units sold, with revenue. Excludes cancelled orders.

get_revenue_report

Revenue grouped by category, year, or month, optionally filtered to one year. Excludes cancelled orders.

Security notes

  • The database connection is opened with { readonly: true, fileMustExist: true } — the SQLite engine itself physically refuses any write, regardless of what SQL is sent.

  • The query tool additionally validates that the input is a single SELECT (or WITH ... SELECT) statement before it ever reaches the database, rejecting INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/ PRAGMA/ATTACH/DETACH/REPLACE/VACUUM/REINDEX/TRIGGER and multi-statement input, with a friendly error message.

  • Errors are caught at each tool's boundary and returned as an MCP tool result with isError: true and a short message — no stack traces or filesystem paths are ever sent to the client.

  • All logs go to stderr (console.error) — stdout is reserved exclusively for the JSON-RPC protocol stream.

Tests

npm test

Runs node --test (via tsx) across every *.test.ts file: unit tests for the SQL guard, the DB connection, and each tool's query logic against the real shop.db, plus an end-to-end test that spawns the compiled server and drives it with a real MCP client over stdio.

Docker

docker build -t db-mcp .
docker run -i db-mcp

Not required to run the server locally (the client config above expects a local node process), but provided as an alternative way to verify/run it.

Available Tools

6 tools
describe_tableA

Get column definitions (name, type, nullable, primary/foreign keys), row count, and a few sample rows for one table. Use this after list_tables to learn exact column names and types before writing SQL in the query tool.

Inputs: table (required).

get_revenue_reportA

Get total revenue grouped by product category, by year, or by month. Cancelled orders are excluded. year optionally restricts results to one year (also applies to 'month' grouping). Use this instead of writing the orders→order_items→products join yourself.

Inputs: group_by (required), year.

get_top_customersA

Get the top customers ranked by total amount spent or by number of orders placed. Cancelled orders are excluded from totals. Use this instead of query for 'who spent the most' / 'who ordered the most' questions.

Inputs: by (required), limit.

get_top_productsA

Get the best-selling products ranked by units sold, with revenue per product. Cancelled orders are excluded. Use this for 'best-selling products' questions instead of writing the order_items→products join yourself.

Inputs: limit.

list_tablesA

List all tables in the shop database with a short description of what each table contains and how many rows it has. Use this first to discover what data is available before writing queries or calling other tools.

Inputs: no named parameters.

queryA

Run a read-only SQL SELECT query against the shop database. Use this for any question not directly covered by the specialized analytics tools, or to explore/join data freely once you know the schema. Only a single SELECT (or WITH ... SELECT) statement is allowed — write operations and multiple statements are rejected. Results are capped at limit rows; use offset to page through more.

Inputs: sql (required), limit, offset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: schema discovery, ad-hoc querying, and specific analytical reports. The specialized analytics tools explicitly tell agents to use them instead of writing equivalent queries, and the query tool remains the catch-all for anything else.

    Naming Consistency5/5

    Tool names consistently follow an imperative verb first pattern: list_tables, describe_table, query, get_top_customers, etc. There is no mixing of naming conventions or vague duplicate verb prefixes, making the set predictable.

    Tool Count5/5

    Six tools is well-scoped for a read-only database MCP server. The set covers discovery, raw querying, and common analytics needs without unnecessary redundancy or bloat.

    Completeness5/5

    For a read-only shop database server, the surface is complete: discover tables, inspect schemas, run arbitrary SELECT queries, and pull common analytics reports. The raw query tool covers edge cases not handled by the specialized reports, so there are no obvious dead ends.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Shop Analytics MCP Server

      bogdaamn
      F
      license
      A
      quality
      C
      maintenance
      Enables AI agents to answer analytical questions about an online store's SQLite database through specialized read-only tools, without any risk of modifying the underlying data.
      8
      -

    • shop-db

      aleksei-antipin
      F
      license
      A
      quality
      C
      maintenance
      Enables AI agents to read-only query an online store's SQLite database, listing tables, inspecting schemas, and running SELECT queries over customers, products, orders, and order items.
      3
      -

    • shop-db MCP Server

      bulychauPI
      F
      license
      A
      quality
      C
      maintenance
      Gives AI agents read-only analytical access to an e-commerce SQLite database (customers, orders, order_items, products) via SQL queries, table listing, and schema inspection.
      3
      -

    • Shop MCP Server

      k0ry
      F
      license
      A
      quality
      C
      maintenance
      Enables AI agents to analyze an SQLite e-commerce database via secure read-only SQL queries, providing tools for table inspection and analytical requests.
      2
      -