Read-only Analytics MCP Server

A clean-room core for exposing warehouse queries as a guarded Model Context Protocol tool. It validates read-only SQL, injects a conservative row limit, requires JSON responses from the upstream API, and returns audit metadata without leaking authentication material.

This repository contains no production account locator, warehouse name, access token, table name, schema, query history, or employer configuration.

What it demonstrates

• MCP tool design for analytics agents

• Read-only SQL validation

• SQL API request construction

• Required content negotiation headers

• Row and statement limits

• Secret-safe error handling

• Auditable query fingerprints

Related MCP server: grane

Safety model

• Only one SELECT, SHOW, or DESCRIBE statement is accepted.

• Mutating keywords, comments, and multiple statements are rejected.

• SELECT queries receive a maximum row limit when one is not already present.

• Tokens are accepted by the transport boundary but never returned or logged.

Run the tests

python -m unittest discover -s tests -v

Run the optional MCP adapter

python -m pip install -e '.[mcp]'
export ANALYTICS_SQL_API_URL='http://localhost:9000/query'
export ANALYTICS_SQL_API_TOKEN='development-placeholder'
python -m readonly_analytics_mcp.mcp_server

The example values are local placeholders. Never commit a real token or private endpoint.

Production extensions

• Replace the lightweight keyword guard with an AST-based SQL parser.

• Add per-tool table allowlists and policy-service authorization.

• Add a streamable-HTTP deployment option alongside the included stdio adapter.

• Add pagination, query cancellation, and structured observability.