CHEQ Churn Insights MCP

A local MCP server for asking questions about the Telco Customer Churn dataset from Codex or Claude Code.

• cheq-churn is the regular, aggregate-only server. It answers counts, churn rates, averages, and comparisons. It never returns customer IDs.

• cheq-churn-trusted is a local demo of privileged lookup workflows. It can discover up to 10 IDs and return selected customer fields. It is not real RBAC: any local user who can edit the MCP configuration can enable it.

Follow these steps to talk to the MCP

1. Clone the repository

git clone https://github.com/Nirerp/cheq-churn-mcp.git
cd cheq-churn-mcp

2. Install dependencies and download the dataset

uv sync --all-groups
make bootstrap

make bootstrap downloads the pinned 7,043-row dataset into the ignored data/ directory. It is not committed to Git.

3. Run the demo

In a terminal, start the mode you want to test:

# Regular server: bootstrap, run checks, then start FastMCP
make demo

# Trusted local demo: bootstrap, run checks, then start FastMCP with lookup tools
make demo-trusted

The server will look idle because it is waiting for STDIO MCP messages. Press Ctrl+C to stop it before the next step: Codex and Claude Code start their own STDIO process.

4. Register the MCP with Codex or Claude Code

Regular server (recommended)

# Codex
make install-codex

# Claude Code
make install-claude-code

Trusted local demo

# Codex
make install-codex-trusted

# Claude Code
make install-claude-code-trusted

These commands register an STDIO server and tell the client how to start it. They do not start a long-running service in your terminal.

5. Restart Codex or Claude Code

The newly registered MCP tools are loaded when the client starts.

6. Ask a question

Regular server examples:

• “What percentage of customers churned?”

• “Which contract has the highest churn rate?”

• “How many churned customers said they don't know why?”

Trusted-demo example:

• “Using only cheq-churn-trusted, give me one customer ID for a customer who churned for an unclear reason.”

Related MCP server: Statistical Testing MCP Server

Docker: what it does and does not do

Docker is optional. It packages the same MCP process into an image; DuckDB runs inside that process, so there is no database container, network port, or Docker Compose stack.

make bootstrap
docker build --tag cheq-churn-mcp:local .

# Regular server
docker run --interactive --rm \
  --mount type=bind,source="$(pwd)/data",target=/app/data,readonly \
  cheq-churn-mcp:local

# Trusted local demo
docker run --interactive --rm \
  --env CHEQ_ENABLE_SNAPSHOT_LOOKUPS=1 \
  --mount type=bind,source="$(pwd)/data",target=/app/data,readonly \
  cheq-churn-mcp:local

After testing the container, press Ctrl+C, then register the MCP with the client you want to use:

# Regular server
make install-codex
make install-claude-code

# Trusted local demo
make install-codex-trusted
make install-claude-code-trusted

The Docker commands above only start an MCP process in a container. They do not connect it to Codex or Claude Code, and the container will wait on standard input.

The make install-* commands above connect the client by having it launch the uv version of the server. They do not attach Codex or Claude Code to the container you just ran; STDIO does not work that way.

To make a client launch the Docker image instead, add a manual STDIO MCP entry whose command is docker run --interactive --rm ..., with an absolute, read-only mount of this clone's data/ directory. No port is required.

Remove a local registration

# Regular server
make remove-codex
make remove-claude-code

# Trusted demo
make remove-codex-trusted
make remove-claude-code-trusted

Manual configuration and supported tools

Run make print-mcp-config or make print-mcp-config-trusted to print ready-to-paste Codex and Claude Code configuration for the uv runtime.

The regular server exposes:

• describe_dataset — supported fields, metric definitions, source version, and limitations.

• analyze_customers — approved aggregate metrics, filters, and groupings.

• data_quality_summary — row count, uniqueness, and core completeness checks.

It rejects raw SQL and unsupported metrics, filters, or groupings with an actionable INVALID_ARGUMENT error. Empty aggregate results are valid and return an empty result. Small grouped results are suppressed below five customers.

Verify repository checks

uv run ruff check .
uv run pytest