parlaibero-mcp

An MCP server that gives AI agents access to ParlaIbero: 10 million plenary interventions from the lower or single chambers of 16 Ibero-American countries, linked to their deputies, deposited in Harvard Dataverse (CC BY 4.0, one DOI per country).

The server downloads each country's dataset once (MD5-verified, straight from Dataverse), loads it into a local DuckDB database and exposes tools to search, count and read it. Nothing is sent anywhere except plain GET requests to Dataverse.

Install

You need uv. No clone is required.

Claude Code

claude mcp add parlaibero -s user -- uvx --from "git+https://github.com/rodrodr/parlaibero-tools#subdirectory=mcp" parlaibero-mcp

Codex CLI

codex mcp add parlaibero -- uvx --from "git+https://github.com/rodrodr/parlaibero-tools#subdirectory=mcp" parlaibero-mcp

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json), Gemini CLI (~/.gemini/settings.json), Windsurf and most other clients use the same block:

{
  "mcpServers": {
    "parlaibero": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rodrodr/parlaibero-tools#subdirectory=mcp", "parlaibero-mcp"]
    }
  }
}

Desktop apps do not always see your shell's PATH: if the server fails to start, replace "uvx" with the full path printed by which uvx (e.g. /Users/you/.local/bin/uvx).

To install it as a regular command instead: uv tool install "git+https://github.com/rodrodr/parlaibero-tools#subdirectory=mcp", then use parlaibero-mcp as the command.

Tools

Getting and understanding the data

Counting words over time

Who speaks and how

Anything else, and reproducibility

The resource parlaibero://about summarises the collection.

Two filters that change results

Most analysis tools take exclude_chair and max_turn_words, and warn when you should use them:

• max_turn_words — the published corpora keep documents read into the record (committee reports, bills, lists) as speech when the record marks no separator. They sit in very long turns and, measured on 3 October 2026, hold 54 % of the speech words in Argentina, 26 % in Uruguay and 25 % in Mexico, against under 1 % in Spain or Brazil. Any rate per million words or share of words is affected; max_turn_words=10000 leaves those turns out, and coverage reports the share per country (long_turn_words_pct).
• exclude_chair — the presiding officer's procedural turns (giving the floor, calling votes) can dominate a group. Comparing women and men deputies in Spain 2016-2023, the most distinctive "women's words" are votación, votos, pausa with the chair in, and mujeres, violencia, igualdad, género without it.

Rows without a date (6,187 in Ecuador, 44 in Costa Rica) are left out of anything by year or period, and the tools say so.

How words are counted

A word is a run of letters, digits or combining marks. Counts are whole-word, case- and accent-insensitive (nacion = Nación), so corrupción does not count anticorrupción — add it as a variant (corrupción+anticorrupción) if you want both. n_words, the precomputed word table and every tool use this same definition, so their figures add up. Single words are served from a precomputed table (instant); phrases and filters by party or deputy scan the text (seconds).

Data model

interventions   country · id_session · id_int · legislature · legislative_session · session_number ·
                date · session_type · intervention_order · speaker_raw · id_dep · speaker_name ·
                sex · party · district · dm_speech · text · n_words
unigrams        word counts of speech rows by country, year and sex (accent-folded)
vocab           display form of each folded word
deputies        country + the core columns of every deputy register
deputies_{iso}  the full register of one country, with its own extra columns
datasets        what is loaded: DOI, version, source, rows, sessions, date range

Things worth knowing before drawing conclusions (the server also tells the agent):

• dm_speech = 1 marks speech. Rows with 0 are cover pages, summaries, vote tallies and reproduced documents; intervention_order = 0 is the session's Prolegomena.
• sex, party and district come from the deputy register and are empty when the speaker is not a linked deputy (ministers, clerks, collective or anonymous voices).
• Coverage, linkage and caveats differ by country: read known_limitations and corpus_info.
• id_session / id_int are stable within a published version, not across versions. Cite the dataset with its version.

Command line

parlaibero-mcp                    # serve MCP over stdio (what clients run)
parlaibero-mcp download SV ES     # download and load countries ('all' for the 16)
parlaibero-mcp import ~/Downloads/parlaibero
parlaibero-mcp status
parlaibero-mcp reindex             # after upgrading from an older version (no re-download)
parlaibero-mcp remove SV

Large countries (Brazil, Mexico, Portugal, Ecuador, Spain: 1-1.5 GB each) are best downloaded from the terminal so a client time-out does not interrupt them. All 16 take about 12 GB of downloads plus 15 GB of database; the downloaded CSVs can be deleted afterwards to save space (~/.parlaibero/data/{ISO}/*.csv), but they are needed to re-import.

Configuration

License

MIT for the code. The data are CC BY 4.0 and are cited per country with their DOI.

Grant PID2022-141706NB-C22 funded by MICIU/AEI/10.13039/501100011033 and by ERDF/EU.