cldf-mcp

cldf-mcp

An MCP server that gives AI assistants grounded access to cross-linguistic data published in the CLDF format. Version 0.1 ships with:

• WALS, the World Atlas of Language Structures: 192 typological features (word order, phonology, morphology…) for 2,660 languages, with sources for every datapoint;
• Glottolog: the catalog of the world's ~27,000 languoids, their classification, alternate names, endangerment and description status.

Language models know WALS exists but are unreliable on specifics: which value a language has for feature 85A, or how many languages combine SOV order with prepositions. This server returns the actual data, with the release it came from and the reference behind it.

What makes it different from a lookup table

• Family-aware counts. Related languages inherit features, so "400 languages do X" can mean "three big families do X". Every count comes with the number of distinct families (from Glottolog) and WALS genera, plus the share of the largest family, so the model can tell a cross-linguistic tendency from the signature of one lineage. WALS's balanced 100- and 200-language samples are available as filters.
• Provenance everywhere. Each answer names the dataset, release and citation; datapoints carry their bibliographic sources and page numbers.
• No silent guessing. bsq is WALS's code for Basque and the ISO code for Bassa, so the server asks instead of picking one. "No data" is never reported as "absent".
• Pinned, verified data. Datasets are fetched from tagged releases and checked against SHA-256 checksums before loading.

Quick start

Requires Python 3.11+ and uv (or pip).

Claude Code

claude mcp add cldf -- uvx cldf-mcp

Claude Desktop and other clients that use an mcpServers config:

{
  "mcpServers": {
    "cldf": {
      "command": "uvx",
      "args": ["cldf-mcp"]
    }
  }
}

On first use the server downloads the pinned releases (about 40 MB) and builds a local SQLite database (about 35 MB) in a few seconds. To do this ahead of time:

uvx cldf-mcp setup

Then ask things like:

• Which languages in WALS are SOV but use prepositions? Are they spread across families?
• Is "VSO implies prepositions" a real tendency? Check it within the WALS 200-language sample.
• Give me Basque's word-order features, with sources.
• How does WALS cover the Austronesian family? Which branches have the most data?

Tools

Tool	What it does
list_datasets	Loaded datasets, release versions, coverage, licenses and citations
find_language	Names (including alternate names and misspellings), ISO 639-3 codes, Glottocodes or dataset codes → ranked candidates with family, macroarea and which entries have data
search_features	Keyword search over feature names, chapters and value labels → feature IDs and possible values
get_feature	Definition, chapter, authors and value distribution, counted by languages, families and genera; optional filters by macroarea, family/subgroup or WALS sample
get_values	Language × feature grid with values, comments, sources and full citations; unresolvable names are reported with candidates instead of failing the call
language_profile	Everything about one language: Glottolog identity, lineage, endangerment, description status and all feature values
filter_languages	Languages matching up to 8 conditions (AND, with exclude), across datasets, with the denominator (languages coded for all conditions) and family counts
crosstab	Two features cross-tabulated: languages, families, genera and largest-family share per cell, zero cells kept, optional macroarea breakdown
classification	Glottolog lineage, children (with how many dataset entries fall under each), sisters
get_source	Full bibliographic references for the source IDs cited in datapoints

Resources:

• cldf://guide/typology-caveats: how to use counts responsibly (sampling bias, areal effects, coverage, citation). The server's instructions point the model to it.
• cldf://datasets: versions, licenses and citations of the loaded data.

All tools are read-only and work offline once the data is prepared.

Configuration

Setting	Default
--data-dir / CLDF_MCP_DATA_DIR	~/.cache/cldf-mcp (Linux), ~/Library/Caches/cldf-mcp (macOS), %LOCALAPPDATA%\cldf-mcp (Windows)
--config / CLDF_MCP_CONFIG	none: extra TOML to add or override datasets (experimental, see below)
--transport	stdio; streamable-http with --host / --port for remote use

Other commands: cldf-mcp info (where data lives, whether it is current) and cldf-mcp setup --force (rebuild).

Adding a dataset (experimental)

Any CLDF StructureDataset whose languages carry Glottocodes can be loaded alongside WALS. Feature tools, family counting and cross-dataset filters work on it automatically:

# my-datasets.toml
[datasets.mydata]
title = "My typological survey"
role = "features"
version = "v1.0"
base_url = "https://raw.githubusercontent.com/me/mydata/v1.0/cldf/"   # or: local_path = "/path/to/cldf"
metadata = "StructureDataset-metadata.json"
license = "CC-BY-4.0"
citation = "Me. 2026. My typological survey."

[datasets.mydata.files]   # every file the loader needs, with optional sha256 checksums
"StructureDataset-metadata.json" = ""
"languages.csv" = ""
"parameters.csv" = ""
"codes.csv" = ""
"values.csv" = ""

cldf-mcp setup --config my-datasets.toml

Data, licenses and citation

The server code is MIT-licensed. The data is not part of this package: it is downloaded from the original releases, which are licensed under CC-BY-4.0. If you publish results obtained with this server, cite the datasets (see DATA_LICENSES.md):

Dryer, Matthew S. & Haspelmath, Martin (eds.) 2013. The World Atlas of Language Structures Online. Leipzig: Max Planck Institute for Evolutionary Anthropology. https://wals.info (CLDF release v2020.6)

Hammarström, Harald & Forkel, Robert & Haspelmath, Martin & Bank, Sebastian. 2026. Glottolog 5.3. Leipzig: Max Planck Institute for Evolutionary Anthropology. https://glottolog.org

This is an independent project and is not affiliated with the WALS, Glottolog or CLDF teams.

Limitations

• WALS reflects the literature up to about 2013, and most features are coded for a few hundred languages. Percentages are of coded languages, not of the world's languages.
• Family counts follow Glottolog, which does not recognise proposed macro-families (e.g. Altaic). Of the 17 WALS languages without a Glottocode, 10 are matched to a Glottolog family through WALS's family or genus name; the other 7 keep WALS's own label (e.g. "Niger-Congo").
• Glottolog's full bibliography is not bundled; its references are returned as links.

Roadmap

• 0.2: Grambank, the first dataset that overlaps with WALS, with side-by-side comparison of related features.
• 0.3: PHOIBLE sound inventories and Lexibank wordlists (get_inventory, get_forms).

Development

git clone https://github.com/hsouf/cldf-mcp && cd cldf-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest                # offline tests on small fixtures (tests/fixtures)
pytest -m network     # downloads the real pinned releases and checks known WALS counts
ruff check src tests && ruff format --check src tests

See RELEASING.md for publishing to PyPI and the MCP Registry.