mcp-server
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-server How fresh are the metrics?"
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-server
A read-only MCP server that gives Claude tools over data-pipeline's published outputs.
flowchart LR
pipeline["data-pipeline"] --> outputs[("parquet/*.parquet<br>quality_report.json<br>contract v1 or v2")]
outputs --> server["mcp-server<br>read-only tools"]
server -- "MCP over stdio" --> claude["Claude"]Key numbers
What | Number | How to check |
Tests | 298, all offline on the copied samples of v1 and v2, in about 6 seconds |
|
Tools | 6, all in the |
|
Copied files | 13: five v1 sample files from data-pipeline's |
|
Size of a | 271 characters, for a live pipeline run | Count the result shown in the quickstart |
The six tools, each on outputs of contract v1 or v2:
metrics_breakdown: one metric split by category or distribution center over a date range; any metric on v2, only the additive ones andreturn_rateon v1.metrics_daily_totals: the published totals of a date range by day, week or month.metrics_explain: the full definition of one metric.metrics_freshness: the run the metrics come from, its data range and its quality status.metrics_list: every metric with its label, unit and whether it is additive.metrics_quality_report: the run's quality status, row counts and checks that did not pass.
A real exchange
On 2026-11-16 the owner asked Claude the same question twice through this server, on the outputs of a live run of data-pipeline: 2,875 days, 2019-01-02 to 2026-11-15. The tools were built by task-agent, the loop that works this repo's issues.
Using the tools server, what were orders by category in October 2026?
Contract v1: Claude answered that the server can't give orders by category, because one order can contain items from several categories. It gave the total, 5,177 orders, and units by category instead.
Contract v2: Claude answered Intimates 536, Tops & Tees 507, Jeans 496, Sleep & Lounge 480, Swim 459 and 21 more categories, and added: "Don't add these up for a total. One order can include items from several categories, so it gets counted in each of them."
Related MCP server: Data Platform MCP Server
Quickstart
Needs uv. It installs Python 3.14 and the locked dependencies.
make install
make checkThe server reads outputs that data-pipeline
published. Its demo writes a set to data/demo/output/, offline; its README says how to run it.
Register the server with Claude Code. <dir> is the full path of the output directory and
<repo> is the full path of this repo:
claude mcp add tools --env DATA_OUTPUT_DIR=<dir> -- uv run --directory <repo> mcp-serverThen ask Claude how fresh the metrics are. Over stdio, metrics_freshness returned this for
the outputs of a live pipeline run against BigQuery:
{
"run_id": "41a81830d9dc495abb3d153e017c78af",
"source": "bigquery",
"contract_version": "v1",
"generated_at": "2026-11-16T14:00:35Z",
"data_min_date": "2019-01-02",
"data_max_date": "2026-11-15",
"restated_from": "2026-11-02",
"quality_status": "pass"
}The demo outputs give the same shape with "source": "fixtures".
How it works
Outputs: each tool call reads
$DATA_OUTPUT_DIR/parquet/<table>.parquetwith a fresh in-memory DuckDB. The server never writes, and there is no default directory: if the variable is unset or a file is missing, the tool says what to set.Contract: docs/contract.md is a copy of data-pipeline's contract v2. The server reads v1 and v2. Every tool starts by loading the run. Outputs with another contract version, or with metric names that differ from the contract's, are refused with a message that says what to do.
Tools: each tool is one function in its group's module, such as src/mcp_server/metrics.py. It is named
<group>_<noun>, marked read-only, and returns a typed result. Ratios are fractions between 0 and 1, rounded to four places in SQL; money is rounded to two places and counts are integers.metrics_breakdownsplits a metric by category or distribution center, largest slice first, at most 50 slices. On v2 it readsdaily_by_categoryordaily_by_distribution_centerand splits every metric, and says whether the slices add up and whether the value is approximate. On v1 it splits onlyrevenue,units,returned_unitsorreturn_rate.metrics_daily_totalsreturns the totals by day, week or month in columns, at most 2,000 values, and marks the periods that may still change.metrics_explainreturns one metric's description, aggregation and formula.metrics_freshnessreturns the run id, source, contract version, data range, publish time and quality status.metrics_listreturns every metric's name, label, unit and whether it is additive.metrics_quality_reportreturns the run's status, the rows each source table gave and at most 50 checks that did not pass.
SQL: queries are built only from constants in this repo. Tool arguments and values read from the data are bound as parameters and never become SQL text.
Errors: an error Claude can act on is a
ToolErrorwith a message that says what to do. The text of any other error stays in the server's log.Transport: stdio. stdout carries the protocol, so the server logs to stderr.
Samples: every test runs on tests/samples/v1/ and tests/samples/v2/, copied from data-pipeline's
contract-v1andcontract-v2tags.SOURCE.jsonrecords the commit and a SHA-256 for each file. A test checks the files against it, and CI compares them with the tag itself.
Limitations
One tool group. The six tools are all in
metrics. On v1 outputs onlyrevenue,units,returned_unitsandreturn_ratecan be split by category or distribution center.Two contract versions. The server reads contract v1 and v2 and refuses anything else.
Local only. It runs as a subprocess of the client over stdio. There is no HTTP transport and no authentication.
No database file. It reads the Parquet files and
quality_report.json. It does not readmetrics.duckdb.No cache. Every call reads the files again, so it always sees the latest published run.
Development
make checkruns the linters and the tests. CI runs the same command, then compares the copied samples with data-pipeline's contract tags, which needs the network.make formatfixes style and formatting.make sync-samplescopies a contract version's samples and contract doc from the tag in a local clone:make sync-samples PIPELINE=../data-pipeline VERSION=v1. Never edit the copies.To add a tool, add a function to its group's module and tests in
tests/test_<group>.py.tests/test_server.pyholds the rules every tool must meet. A new group is a new module named inGROUPSin src/mcp_server/cli.py.
License
MIT, see LICENSE.
Available Tools
6 toolsmetrics_breakdownARead-only
One metric split by by, category or distribution_center, over start to end (ISO dates, both included). slices holds each slice's name and value, largest first; at most 50 are returned, and truncated says whether there were more. Counts and money are summed over the days, and aov, return_rate and conversion_rate are recomputed from the slice's summed parts; a ratio is null when its denominator is 0. Ratios are fractions between 0 and 1, rounded to four places. orders, product_view_sessions and converted_sessions are distinct within the slice, and they and every ratio must not be summed across slices; a slice's aov is revenue per order in that slice. adds_up says whether the slices add up to the total, true only for revenue, units and returned_units. approximate is true for the session metrics over more than one day, because a session that crosses midnight is counted on both days. On contract v1 outputs only revenue, units, returned_units and return_rate can be split; call metrics_daily_totals for the others. includes_provisional is true when the range reaches restated_from, so the numbers may still change. Call metrics_freshness for the dates the data covers and the contract version.
Inputs: by (required), end (required), start (required), metric (required). Returns: One metric of a date range split into slices, largest first.
metrics_daily_totalsARead-only
The published totals from start to end (ISO dates, both included) by grain: day, week (starting Monday) or month. It returns columns: dates holds the first day of each period that falls in the range, and values holds one list per metric, lined up with dates. metrics picks the metrics; leave it out for all of them. At week and month, counts and money are summed and aov, return_rate and conversion_rate are recomputed from the summed parts; a ratio is null when its denominator is 0. Ratios are fractions between 0 and 1, rounded to four places. The session metrics, named in approximate, are approximate above day, because a session that crosses midnight is counted on both days. A period is provisional when any of its days is on or after restated_from, so its numbers may still change. Call metrics_freshness for the dates the data covers and metrics_list for the metric names.
Inputs: end (required), start (required), grain, metrics. Returns: The totals of a date range in columns, one entry per period.
metrics_explainARead-only
The full definition of one metric: its name, display label, unit (usd, count or ratio), whether it is additive, a plain-language description, its aggregation (sum, count, count_distinct or ratio) and its formula. Ratios are fractions between 0 and 1, rounded to four places. Call it before explaining what a number means. Call metrics_list for the valid names.
Inputs: name (required). Returns: One metric with its full definition.
metrics_freshnessARead-only
Which pipeline run the metrics come from: its id, source, contract version, data range (data_min_date to data_max_date), publish time (generated_at, UTC) and quality status. Call it to learn what dates the data covers and how fresh it is. Rows dated on or after restated_from may still change on later runs.
Inputs: no named parameters. Returns: The pipeline run that published the outputs.
metrics_listARead-only
Every published metric in contract order: its name, display label, unit (usd, count or ratio) and whether it is additive. A metric is additive when summing it across categories and distribution centers gives the total. orders, the session counts and every ratio are not additive, because one order or session can span several slices. Ratios are fractions between 0 and 1, rounded to four places. Call metrics_explain for one metric's full definition.
Inputs: no named parameters. Returns: Every metric of the contract, in contract order.
metrics_quality_reportARead-only
What the pipeline checked on the run the metrics come from: the run's status (pass, warn or fail), the rows_ingested and rows_quarantined of each source table in tables, and the checks that did not pass in failed_checks, each with its name, table, severity, status and message. At most 50 are returned: more_failed counts the ones left out, and passed_checks counts the checks that passed. Look here before trusting a number from a run whose status is not pass; metrics_freshness gives that status as quality_status.
Inputs: no named parameters. Returns: The run's quality report, with only the checks that did not pass.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a clearly different need: slice-by-dimension (breakdown), time series (daily_totals), metadata (list/explain), and pipeline trust (freshness/quality_report). The only mild overlap is between metrics_freshness and metrics_quality_report, since freshness surfaces quality_status and points to the report, but the split between run identity/date coverage and check-level detail is explained well.
All six tools share the metrics_ namespace prefix and snake_case suffixes, giving a strongly predictable pattern. The suffixes mix verbs (explain, list) with nouns (breakdown, daily_totals, quality_report, freshness), which is a minor deviation but still very readable.
Six tools is well-scoped for a metrics query server: discovery (list, explain), retrieval (daily_totals, breakdown), and trust (freshness, quality_report) each get dedicated tools with no filler. Nothing looks redundant or missing at the count level.
The surface covers the full query lifecycle—discover metrics, understand definitions, pull totals and breakdowns across grains, and verify data currency and quality—with no obvious dead ends. The main gap is there is no way to enumerate valid `by` dimensions or category/distribution-center values, so an agent must discover them by trial or from breakdown results.
Maintenance
Related MCP Connectors
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Read-only MCP for identity resolution and write guardrails.
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
Related MCP Servers
- AlicenseBqualityCmaintenanceA read-only MCP server that exposes dbt project artifacts and data quality result tables (BigQuery/Postgres) to LLM clients, enabling deep introspection, run-history analysis, source freshness, test coverage, and lineage walks.2742 npmMIT
- AlicenseBqualityBmaintenanceEnables MCP hosts like ChatGPT and Claude to query data platform metadata, explore schemas and tables, inspect SQL explain plans, and monitor DAG and ETL status through standardized tools.21MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to discover schemas, keys, and lineage across bronze, silver, and gold tables, and to run guarded read-only SQL queries against the lakehouse.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables language models to safely explore lakehouse tables and governed metrics, run guarded read-only SQL, and inspect pipeline health and data-contract violations through MCP tools.MIT