CHEQ Ticket Intelligence MCP

Local setup instructions for the customer-support ticket MCP server.

Requirements

• macOS or Linux.
• uv. The project uses Python 3.12 from .python-version and supports Python 3.11-3.13.
• An OpenAI Platform API key with embedding access.
• Codex CLI and/or Claude Code CLI.
• Network access and at least 2 GB of free space for dependencies, the dataset cache, and about 891 MB of generated SQLite/LanceDB artifacts.

uv sync --locked installs the locked runtime packages: datasets, lancedb, mcp, openai, pyarrow, and pydantic. It also installs the development packages pytest and mcp[cli].

Dataset and license

This project uses the synthetic Customer Support Tickets dataset by Tobi Bueck. Ingestion is pinned to the train split at revision ddf1c81a5475992c4fa6752bf1e8b4e31f07bbeb, which contains 61,765 tickets.

The dataset is licensed under CC BY-NC 4.0. Its use is limited to non-commercial purposes and requires attribution. This dataset license is separate from the repository's MIT code license. The repository does not redistribute the source dataset or generated SQLite, LanceDB, or embedding artifacts; the documented ingestion command builds them locally from the pinned source.

1. Install

Install uv if needed:

# macOS
brew install uv

# Or macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

From a fresh clone:

git clone https://github.com/GalDaich/cheq-cs-tickets-mcp.git
cd cheq-cs-tickets-mcp
uv sync --locked

2. Configure the API key

This server uses OpenAI text-embedding-3-large for ticket and query embeddings only. Codex or Claude Code selects the MCP tool and writes the final answer.

The only environment variable is OPENAI_API_KEY. It is required for ingestion and semantic search. Exact analytics and ticket lookup remain local after the data has been built.

Create the ignored local environment file and add the key:

cp .env.example .env.local
chmod 600 .env.local
${EDITOR:-vi} .env.local

.env.local should contain:

OPENAI_API_KEY=your_openai_api_key

Never commit .env.local or place the API key directly in an MCP registration command.

3. Build the local data

The first build downloads the pinned 61,765-row dataset and creates the local SQLite and LanceDB artifacts. Embedding the dataset uses the OpenAI API and may incur cost.

set -a
. ./.env.local
set +a
uv run --locked cheq-tickets-ingest

If the local artifacts are stale or incompatible, rebuild explicitly:

uv run --locked cheq-tickets-ingest --rebuild

4. Run the server directly

set -a
. ./.env.local
set +a
uv run --locked cheq-tickets-mcp

A silent, blocked process is expected: stdio is the MCP protocol transport. Stop the direct process with Ctrl-C; normally Codex or Claude Code starts it.

5. Connect Codex CLI

Run from the repository root. The saved command uses absolute paths and loads .env.local without copying its values into Codex configuration.

PROJECT_ROOT="$(pwd)"

codex mcp add cheq-tickets -- \
  /bin/sh -c "set -a; . \"$PROJECT_ROOT/.env.local\"; set +a; exec \"$PROJECT_ROOT/.venv/bin/cheq-tickets-mcp\""

codex mcp get cheq-tickets --json
codex mcp list

Start a new codex session and run /mcp to confirm that cheq-tickets exposes search_tickets, analyze_dataset, and get_ticket. See the official Codex MCP documentation.

6. Connect Claude Code CLI

Run from the repository root. Local scope keeps the registration private to the current user and project.

PROJECT_ROOT="$(pwd)"

claude mcp add --transport stdio --scope local cheq-tickets -- \
  /bin/sh -c "set -a; . \"$PROJECT_ROOT/.env.local\"; set +a; exec \"$PROJECT_ROOT/.venv/bin/cheq-tickets-mcp\""

claude mcp get cheq-tickets
claude mcp list

Start a new claude session and run /mcp to confirm the three tools. See the official Claude Code MCP documentation.

7. Verify

In either connected host, ask:

How many tickets are in the pinned dataset, grouped by language?

The counts should total 61,765. Then verify semantic search:

Find three tickets about VPN connection failures and cite each TKT ID.

For local deterministic checks:

uv run --locked pytest