DB MCP (HR CSV → SQLite) — Open Source Reference

This folder contains a fully open-source Model Context Protocol (MCP) server implementation that:

Loads an HR “people” CSV file
Reads 3 lines of metadata at the top of the CSV (comment lines starting with #)
Imports the CSV into an in-memory SQLite database
Exposes read-only MCP tools over stdio (newline-delimited JSON-RPC 2.0)

No Claude Desktop setup is required. A small Python client is included for testing.

Files

db_mcp_server.py — MCP server (stdio)
db_mcp_client.py — simple MCP stdio client for testing
data/hr_people.csv — sample HR CSV with 3-line metadata header

Run the server

python db_mcp_server.py

Optionally pass a custom CSV path:

python db_mcp_server.py /path/to/your/hr_people.csv

Or set an environment variable:

HR_CSV_PATH=/path/to/your/hr_people.csv python db_mcp_server.py

Test with the included client (recommended)

python db_mcp_client.py

You should see:

initialize handshake
tools/list
a sample SQL query result
an interactive prompt to run more SELECT queries

Tools exposed

hr_metadata — returns the 3-line metadata header as a JSON object
hr_schema — returns the SQLite schema for table employees
hr_query — execute read-only SELECT/WITH SQL queries
hr_find_people — structured search without writing SQL

CSV metadata format (first 3 lines)

Example:

# dataset: HR People
# description: Synthetic employee roster for MCP demo (no real PII)
# primary_key: employee_id
employee_id,first_name,last_name,...

Metadata lines are parsed as key: value. If a line is not key: value, it is stored as meta_line_1, meta_line_2, etc.

Notes for sharing

Everything here is standard-library Python (SQLite + CSV).
The demo data is synthetic (no real PII).
The server writes only JSON-RPC to stdout. Logs go to stderr (safe for stdio MCP).

MCP_DB