chalktalk
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., "@chalktalk How many star players had under 15 snaps in 2023?"
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.
chalktalk
An MCP server for composite NFL questions where the hard part is agreeing on what the words mean.
Status: working. Ingest, the feature layer, definitions and the MCP server are in place. See
docs/plan/00-index.mdfor the phase ledger.
The problem
Take a real question:
"How many times have star players played fewer than 15 snaps before leaving with injury? Total by season."
Three of those phrases have no corresponding field anywhere in the data:
"star players" — no such marker exists. Prior-season snap share above some percentile? Draft capital? Pro Bowl selection? Contract APY? Each yields a different answer.
"before leaving with injury" — nothing records in-game exits. The injuries table is the weekly report — practice participation and game designation, published before kickoff. Exits have to be inferred.
"fewer than 15 snaps" — the only clean one, and it still needs a decision about whether special teams counts.
A text-to-SQL system will silently pick definitions and return a confident number. chalktalk refuses to do that.
Related MCP server: NFL Analytics MCP
The definition gate
The query tool rejects any call containing an unresolved term:
{ "error": "unresolved_term",
"term": "star_player",
"message": "No definition found. Call propose_definition first.",
"suggestions": ["..."] }propose_definition then returns candidates grounded in what is actually
computable, each tagged with the seasons it covers. You pick or edit. The choice
is saved and reused silently from then on, and every answer states which
definitions produced it.
Over time you accumulate a personal metric vocabulary you never sat down to design. This inverts the usual semantic-layer model, where a data team authors definitions up front.
Install (development)
Requires Python 3.12+ and uv.
uv syncuv run chalktalk doctordoctor prints the resolved paths under CHALKTALK_HOME (default
~/.chalktalk), whether a built database is present, and the versions of duckdb,
nflreadpy and polars it will use.
uv run pytestThe default run is the unit tier and needs no data. Tests that require a built
database are marked data and are opt-in: uv run pytest -m data.
Once a database exists, install the shipped vocabulary:
uv run chalktalk defs installThat is 45 definitions — early_exit, blowout, heavy_carries and so on —
all ordinary specs you can read with chalktalk defs show NAME and change.
star_player is deliberately not among them.
Building the database
uv run chalktalk buildThis downloads every nflverse dataset from the 2013 season on and writes one
immutable ~/.chalktalk/data/nfl-YYYYMMDD.duckdb, then points CURRENT at it.
Roughly a minute and 720 MB. --plan shows what would be downloaded without
downloading anything; --seasons and --only narrow it.
The file is disposable — rebuild it weekly and nothing is lost, because
definitions live outside it under ~/.chalktalk/definitions/.
Connect
Build the database first, then point an MCP client at the server.
claude mcp add chalktalk -- uv --directory /path/to/chalktalk run chalktalk serveFor Claude Desktop, the equivalent in claude_desktop_config.json:
{
"mcpServers": {
"chalktalk": {
"command": "/absolute/path/to/uv",
"args": ["--directory", "/path/to/chalktalk", "run", "chalktalk", "serve"],
"env": { "CHALKTALK_HOME": "/Users/you/.chalktalk" }
}
}
}Give command the absolute path to uv — which uv will tell you, commonly
~/.local/bin/uv. A bare "uv" works for claude mcp add, which inherits your
shell, but Claude Desktop is launched by the OS and does not get your PATH; it
fails to start the server with an error that does not mention PATH. Quit
Desktop completely and reopen it after editing the file — closing the window is
not enough.
CHALKTALK_HOME defaults to ~/.chalktalk and holds the database, your
definitions and the audit log. Pass it explicitly if you keep them elsewhere.
The server exposes eleven tools. The ones that matter to a person:
propose_definition when a word has no agreed meaning yet, save_definition
once you have chosen, query to ask, and raw_sql for the questions the tool
surface cannot yet express. Every query answer carries the definitions it
used, the seasons it covered, a sample of matched rows and the SQL.
What a session looks like:
you How many times have star players played fewer than 15 snaps
before leaving with injury? By season.
→ unresolved_term: star_player
star_by_snaps top 10% of snap share last season, within position group
star_by_contract top 10% of pay as a share of the cap, within position group
star_by_draft a first-round pick
you the contract one
→ saved star_player, copied from star_by_contract
→ Count of player-games (REG, 2013–2025) where star_player [prior season]
and early_exit and snaps_unit < 15, by season.
2013 2 2016 5 2019 3 2022 6
2014 4 2017 7 2020 4 2023 5
…
definitions used: star_player, early_exit, played, regular, left_early,
snap_drop, exit_evidence, listed_injured_next, on_reserve_soon,
started, missed_next_game_as_starter, exit_corroborated
warning: participation evidence is unavailable before 2016; snap_drop
carries the evidence in 2013–2015The refusal is the point. Ask again next week and it answers straight away,
because star_player now means the thing you chose — and every answer says so.
Three things always come back with the number: the definitions behind it, the seasons it could actually cover, and a sample of the matched rows. That last one matters more than it sounds. A rested starter in the final week looks identical in the data to an injury exit, so the rows are how you catch a wrong one.
Your definitions
They live in $CHALKTALK_HOME/definitions/, one JSON file each, outside the
database — which is discarded and rebuilt every week. Losing them to a data
refresh would be the worst bug this could have, so they are kept somewhere a
rebuild cannot reach.
cd ~/.chalktalk/definitions && git init && git add -A && git commit -m "my vocabulary"That is the whole backup story: they are plain JSON, so they diff, they merge,
and you can edit one by hand and the server picks it up. Previous versions are
kept under .history/ whenever you overwrite or delete one.
uv run chalktalk defs list # what you have
uv run chalktalk defs show early_exit # what it means, all the way down
uv run chalktalk defs export ~/backup # or import, for sharing a setchalktalk logs terms tells you which of them you actually reach for, and which
raw fields you keep spelling out instead of naming.
Rebuilding
The database is disposable and versioned by date. Rebuild it weekly during the season — the whole thing takes about a minute and the old artifact stays on disk.
0 6 * * 3 /Users/you/.local/bin/uv --directory /path/to/chalktalk run chalktalk buildOn macOS, launchd is more reliable than cron for a laptop that sleeps. Save this
as ~/Library/LaunchAgents/com.chalktalk.build.plist and
launchctl load it:
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict>
<key>Label</key><string>com.chalktalk.build</string>
<key>ProgramArguments</key>
<array>
<string>/Users/you/.local/bin/uv</string>
<string>--directory</string><string>/path/to/chalktalk</string>
<string>run</string><string>chalktalk</string><string>build</string>
</array>
<key>StartCalendarInterval</key>
<dict><key>Weekday</key><integer>3</integer><key>Hour</key><integer>6</integer></dict>
<key>StandardErrorPath</key><string>/tmp/chalktalk-build.log</string>
</dict></plist>Rollback is editing one file. data/CURRENT holds the filename the server
opens; point it at the previous artifact and the next tool call picks it up
without a restart.
ls ~/.chalktalk/data/ # the last three builds are kept
echo nfl-20260901.duckdb > ~/.chalktalk/data/CURRENTchalktalk doctor will tell you what is currently loaded, how old it is, and
whether any of your definitions stopped compiling against it.
Design
Architecture and rationale: CLAUDE.md.
Rejected alternatives and why: docs/decision-history.md.
The short version: one process, one DuckDB file on local disk, 2013 season floor, Python. Definitions are stored as specs rather than SQL and live outside the database, which is discarded and rebuilt weekly.
Data and attribution
Data comes from nflverse, via
nflreadpy. chalktalk distributes code, not data — you pull from nflverse
yourself when you build the database.
Two distinct layers, worth keeping separate:
The compiled nflverse dataset is licensed CC BY 4.0 (attribution, no ShareAlike).
The underlying NFL data belongs to its respective owners and is governed by their terms of use. nflverse does not claim to grant rights to it, and neither does this project.
The MIT license on this repository covers this project's code only. It grants no rights to NFL data.
Credits
nflverse for the data infrastructure this is built on.
nfl-mcp(MIT) — the ingest module here is adapted from theirs, with the notice retained. It solves a different problem well: if you want a fantasy football tool, use it rather than this.
License
MIT — see LICENSE.
Available Tools
11 toolsbuild_statusA
What this server is running on: which database artifact, when it was built, the seasons it holds, whether the latest is still in progress, how many definitions exist and how many are broken.
Inputs: no named parameters. Returns: object
coverageA
The seasons a thing can answer for. Accepts table.column, entity.attribute, or the name of a definition. A query is refused when what it asks for reaches outside this window, so check here before promising a range.
Inputs: ref (required). Returns: object
delete_definitionA
Delete a definition. Its previous version is kept in history, so this is recoverable. Anything built on top of it becomes broken until it is replaced.
Inputs: name (required). Returns: object
describe_schemaA
Describe what can be queried: the six entities (game, team_game, team_season, player_game, player_season, play), their namespaces (e.g. prior., game., next.), and every attribute with its coverage window. Attributes are the only raw fields a plan may reference. Anything that is a concept rather than a field — "star", "starter", "injury", "blowout" — must be a term: see list_definitions and propose_definition.
Inputs: entity, include_play_columns. Returns: object
explain_queryA
Dry run. Shows the English reading of the plan, which definitions it will use, the seasons it will cover, warnings, and the SQL. Use it to confirm your interpretation with the user before running an expensive or ambiguous query.
Inputs: plan (required). Returns: object
get_definitionA
Everything about one definition: its spec, a nested English explanation of the definitions it is built from, the attributes it uses as evidence, its coverage, and its previous versions.
Inputs: name (required). Returns: object
list_definitionsC
The user's vocabulary. Every term used in a query must be here. Broken definitions (a column they depend on disappeared) are listed with the reason and cannot be used until fixed.
Inputs: family, include_broken. Returns: object
propose_definitionA
Call this when a query needs a concept that has no definition yet, or when query returns unresolved_term. Returns existing near-matches, ready-to-save candidate definitions grounded in what the data can compute (each with an English explanation and coverage), related attributes, and the five signal schemas for composing something new. Present the candidates to the user and let them choose or adjust. Do not pick one silently.
Inputs: term (required), entity, context. Returns: object
queryA
Run a structured query. plan is {entity, where, seasons, game_types, group_by, metrics, order_by, limit, allow_partial_coverage, sample_rows, question}; where clauses are {"term": name} for concepts, {"attr": name, "op": …, "value": …} for raw fields, and {"not"|"any_of"|"all_of": …} to combine. Every fuzzy word in the user's question must be a term. If a term has no definition this tool returns unresolved_term — do not replace it with an attribute rule to get past the error; call propose_definition and ask the user. The result includes definitions_used, the seasons actually covered, a sample of matched rows and the SQL; report the definitions and coverage alongside the number, because the number is not meaningful without them. If warnings mention evidence unavailable for early seasons, say so.
Inputs: plan (required). Returns: object
raw_sqlA
Escape hatch: read-only SQL over every raw and derived table (see describe_schema and coverage). A single SELECT or WITH statement, row cap, timeout, no file or network access. Results carry no definitions — prefer query for anything involving a concept, and tell the user when a number came from raw SQL. Every call is logged; recurring raw queries are how new attributes get prioritised.
Inputs: sql (required), limit. Returns: object
save_definitionB
Save a definition the user has chosen. copy_of copies an existing definition (e.g. star_by_snaps) under a new name. Saving is versioned; previous versions are kept. Tell the user what was saved in plain English — the returned explanation is written for that.
Inputs: name (required), basis, entity, params, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct facet: schema/coverage metadata, definition management, query execution, and operational status. There is no functional overlap; query and explain_query are clearly separated as execution vs. dry run.
Most tools follow a verb_noun pattern in snake_case (describe_schema, list_definitions, save_definition). Minor outliers like query, raw_sql, coverage, and build_status break the strict pattern but remain perfectly readable.
Eleven tools is well within the ideal range and each one earns its place: two for metadata, five for definition lifecycle, three for querying, and one for status. The count matches the server's scope with no redundancy.
The surface covers discovery, definition management (create, read, update via versioned save, delete), and all query modes (dry run, structured, raw). Build status adds operational completeness, and versioning covers recovery.
Maintenance
Related MCP Connectors
Verified answers from your data, with the query and rows behind them, or a decline, never a guess.
Architecture-grounded query for AI agents. Governance constraints, evidence-linked answers.
Answers about your own company from its recorded knowledge, and shows where its sources disagree.
Multi-expert decision intelligence with transparent synthesis and auditable workflows.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables natural language querying of OLAP/SSAS cubes with verified MDX generation, self-consistency checks, and honest abstention when queries are ambiguous.4Apache 2.0
- AlicenseAqualityDmaintenanceEnables natural-language querying of a local DuckDB warehouse of NFL play-by-play data, converting questions into SQL and returning results.191MIT
- AlicenseNot gradedqualityBmaintenanceEnables natural-language queries over data warehouses with catalog-grounded semantics and per-query authorization, returning answers with attached reasoning.Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents and software to detect ambiguous wording in text and receive location, category, explanation, and suggested clarification questions for each signal.1Apache 2.0