Catalunya Open Data MCP

A read-only Model Context Protocol server for discovering, describing, and querying public datasets from Catalunya.

The server currently supports the Generalitat de Catalunya open data portal powered by Socrata, IDESCAT Tables v2, and Open Data BCN. It exposes small, reliable workflows: search or browse catalogs, inspect schemas or dimensions, query bounded extracts, run BCN geospatial scans, preview safe CSV/JSON downloads, and keep enough provenance to cite the source cleanly.

Why This Exists

Open data portals are rich, but they are not always pleasant to explore from a chat interface. This server gives MCP clients a structured way to answer questions such as:

• "Find datasets about housing starts and completions."

• "Which fields can I query in this dataset?"

• "Show the latest rows for Girona, using valid API field names."

• "Preview Barcelona street-tree data or query DataStore-active city equipment."

• "Count tree species on Carrer Consell de Cent or find facilities near a coordinate."

• "Create a citation for the dataset and include the source URL."

Every data-returning tool includes provenance, response caps, and structured errors so the model can recover from bad filters instead of guessing.

For copy-paste task examples, see COOKBOOK.md.

Requirements

• Node.js 22.12 or newer

• npm 10 or newer

Install

npm install
npm run build

This is a local stdio MCP server. In normal use, your MCP client starts dist/index.js and communicates with it over stdin/stdout.

Connect an MCP Client

After building, add a stdio server entry like this to your MCP client configuration:

{
  "mcpServers": {
    "catalunya-opendata": {
      "command": "node",
      "args": ["/absolute/path/to/catalunya-opendata-mcp/dist/index.js"]
    }
  }
}

For active development, point the client at the TypeScript watcher instead:

{
  "mcpServers": {
    "catalunya-opendata": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/absolute/path/to/catalunya-opendata-mcp"
    }
  }
}

The built node dist/index.js path is the most predictable setup for day-to-day use. The watcher is useful while changing the server.

MCP Surface

Tools

Prompts

Resources

Socrata Workflow

Use the tools in this order when answering data questions.

1. Search

Call socrata_search_datasets with the user's topic:

{
  "query": "Habitatges iniciats acabats",
  "limit": 10
}

Each result includes a source_id, web_url, api_endpoint, update timestamp, and provenance. Keep the source_id for the next step.

2. Describe

Call socrata_describe_dataset before writing filters or selecting columns:

{
  "source_id": "j8h8-vxug"
}

Use the returned columns[].field_name values in SODA clauses. Do not use display names, translated labels, or column names with spaces unless they are returned as field_name.

3. Query

Pass clause values only. Do not include URL fragments such as ?$where=.

{
  "source_id": "j8h8-vxug",
  "select": "municipi, comarca_2023, any",
  "where": "municipi = 'Girona'",
  "order": "municipi, any",
  "limit": 10
}

For stable pagination, always include order when using offset:

{
  "source_id": "j8h8-vxug",
  "select": "municipi, comarca_2023, any",
  "order": "municipi, any",
  "limit": 25,
  "offset": 50
}

For aggregate queries, combine aggregate functions in select with group:

{
  "source_id": "j8h8-vxug",
  "select": "comarca_2023, count(*) as total",
  "group": "comarca_2023",
  "order": "total desc",
  "limit": 10
}

4. Attach Metadata

When your MCP client supports resources, attach the dataset metadata directly:

socrata://datasets/j8h8-vxug/metadata

The resource body is the dataset metadata object itself, without the tool-call envelope. It is useful context for follow-up queries and citations.

5. Cite

Use socrata_citation with socrata_describe_dataset output or the metadata resource. A concise citation should include the dataset title, attribution, source domain or URL, last updated timestamp, and license or terms when available.

IDESCAT Workflow

Use idescat_search_tables for topic discovery, or browse with idescat_list_statistics, idescat_list_nodes, and idescat_list_tables. Search can recognize geography words such as comarca, municipi, municipal, and provincia, plus named places such as Maresme, Barcelonès, and Girona; prefer results whose geo_candidates include the requested geography, then confirm the geo_id with idescat_list_table_geos. It also handles common semantic aliases such as taxa atur, paro, renda per capita Maresme, and poblacio municipal without changing the tool inputs. Every metadata and data request requires a territorial division, so call idescat_list_table_geos before fetching a table.

IDESCAT support is scoped to Tables v2. Idescat topic pages may list inactive statistics, additional statistics, or statistics from other organisms that are not exposed through this connector.

Named-place workflow example:

{
  "query": "renda per capita Maresme",
  "lang": "ca",
  "limit": 5
}

After choosing an RFDBC result with com in geo_candidates, call idescat_list_table_geos and select geo_id: "com". Then pass the original place phrase into metadata:

{
  "statistics_id": "rfdbc",
  "node_id": "13302",
  "table_id": "21197",
  "geo_id": "com",
  "lang": "ca",
  "place_query": "Maresme"
}

When filter_guidance.recommended_data_call is present, use it as the starting point for idescat_get_table_data; it contains only actual metadata category IDs and neutral defaults such as TOTAL or single-category dimensions.

Call idescat_get_table_metadata before querying. Use the returned dimension IDs and category IDs in idescat_get_table_data.filters, and use last to request the latest time periods:

{
  "statistics_id": "pmh",
  "node_id": "1180",
  "table_id": "8078",
  "geo_id": "com",
  "lang": "en",
  "filters": {
    "COM": ["01", "TOTAL"],
    "SEX": "F"
  },
  "last": 2,
  "limit": 20
}

IDESCAT data tools are for bounded extracts, not exhaustive table export. If the upstream API returns narrow_filters, reduce dimensions with filters or _LAST_. For citations, use idescat_get_table_metadata or the IDESCAT metadata resource; search/list operation provenance is only an operation trace.

To manually verify the live IDESCAT journey, run npm run canary:idescat. It builds the server, then checks search -> geos -> metadata -> bounded data against a known PMH table using the public MCP tool surface.

Open Data BCN Workflow

Use Open Data BCN for Barcelona city datasets such as street trees, equipment, mobility, facilities, and municipal services. For common city questions, start with bcn_recommend_resources; it returns likely resources, suggested tools, and example arguments. Use package search when the recommender is too narrow or the topic is not covered, then choose DataStore query, geospatial query, or download preview based on the resource metadata and the user's question.

1. Recommend Or Search

{
  "query": "facilities in Gracia district",
  "task": "within",
  "place_kind": "district",
  "limit": 3
}

For open-ended discovery, search packages directly:

{
  "query": "arbrat viari",
  "limit": 5
}

Keep the returned package_id, then call bcn_get_package:

{
  "package_id": "27b3f8a7-e536-4eea-b025-ce094817b2bd"
}

Each resource includes resource_id, format, URL, and datastore_active.

2. Plan Or Execute A City Question

Use bcn_plan_query when the user asks a natural city question and you want an inspectable workflow:

{
  "query": "tree species on Carrer Consell de Cent",
  "limit": 10
}

The planner returns status, deterministic intent, recommended resources, optional place-resolution candidates, ordered steps, final_tool, final_arguments, and citation guidance. place_kind: "point" maps to resolver kinds ["landmark", "facility"]; street, neighborhood, and district pass through. Grouped prompts choose group_by deterministically: explicit input first, then neighborhood grouping for within-area questions, then the first recommended grouping field.

Use bcn_execute_city_query for the same input when a one-call bounded raw result is acceptable. It executes only when the plan is ready; otherwise it returns execution_status: "blocked" with the plan. For area plans, it copies selected_candidate.area_ref into within_place.{source_resource_id,row_id,geometry_field}. If no area_ref is available but a resolver bbox is available, it uses bbox with a caveat; if neither exists, the plan is blocked/unsupported.

Use bcn_answer_city_query when callers need a ready-to-display deterministic answer. It runs the same executor, then returns answer_text, answer_markdown, answer_type, compact summary, deduped warning caveats such as bbox fallback or scan caps, informational execution_notes such as SQL pushdown mode or bounded download scans, selected resource metadata, citation guidance, and the raw final_result. Blocked answers include normalized selection_options with labels, provenance, confidence, and resume_arguments; row summaries include labels and selected fields for display plus summary.rows[].source_row for client drill-down without re-parsing final_result. Row and nearest summaries also include summary.map_points[] when coordinates are available, with {label, lat, lon, distance_m?, source_row} for map rendering.

3. Inspect A Resource

Call bcn_get_resource_info before querying:

{
  "resource_id": "52696168-d8bc-4707-9a09-a21c6c2669f3"
}

If datastore_active is true, the response includes queryable fields.

4. Query Active DataStore Resources

bcn_query_resource always uses POST JSON. Filters are structured CKAN DataStore filters, not SQL text or URL fragments:

{
  "resource_id": "52696168-d8bc-4707-9a09-a21c6c2669f3",
  "fields": ["_id", "Districte", "Barri"],
  "filters": {
    "Districte": "Sant Martí"
  },
  "limit": 10
}

The response includes request_body with the logical replayable request, row counts, truncation flags, and provenance.

5. Resolve Named Places

Use bcn_resolve_place when the user gives a place name instead of coordinates. The resolver is source-bounded: it queries an explicit Open Data BCN DataStore registry, ranks matching rows locally, and returns candidate WGS84 points with matched fields and source provenance. The registry covers building-address street points, administrative district and neighborhood boundaries, municipal facilities, and parks/gardens. District and neighborhood candidates include bbox plus area_ref when BCN exposes WGS84 boundary geometry; pass area_ref to bcn_query_resource_geo.within_place for "in this district/neighborhood" questions.

{
  "query": "Sagrada Familia",
  "kinds": ["landmark"],
  "limit": 3
}

Street and area names use the same tool:

{
  "query": "Plaça Catalunya",
  "kinds": ["street"],
  "limit": 3
}

{
  "query": "Gracia",
  "kinds": ["district", "neighborhood"],
  "limit": 5
}

Use the best point candidate's lat and lon in bcn_query_resource_geo.near. For district and neighborhood candidates, prefer within_place when area_ref is present. Optional resolver bbox and kinds filters can narrow ambiguous names.

6. Query Resources Geospatially

Use bcn_query_resource_geo when the resource has WGS84 coordinate fields. It works across DataStore-active resources and safe BCN-hosted CSV/JSON downloads. DataStore resources with near, bbox, or within_place use generated datastore_search_sql internally so spatial narrowing happens upstream; callers still provide only structured inputs, never raw SQL. within_place first applies the resolved area's bbox upstream, then validates exact polygon containment locally. The tool infers common latitude/longitude pairs such as latitud / longitud, geo_epgs_4326_lat / geo_epgs_4326_lon, and geo_epgs_4326_y / geo_epgs_4326_x; if multiple pairs exist, pass lat_field and lon_field. It does not convert ETRS89 x/y fields.

Street or name matching uses contains:

{
  "resource_id": "23124fd5-521f-40f8-85b8-efb1e71c2ec8",
  "contains": {
    "espai_verd": "Carrer Consell de Cent"
  },
  "group_by": "cat_nom_catala",
  "fields": ["espai_verd", "adreca", "cat_nom_catala"],
  "limit": 10
}

Nearby queries use explicit coordinates:

{
  "resource_id": "d4803f9b-5f01-48d5-aeef-4ebbd76c5fd7",
  "near": {
    "lat": 41.4036,
    "lon": 2.1744,
    "radius_m": 750
  },
  "fields": ["name", "addresses_road_name", "addresses_neighborhood_name"],
  "limit": 10
}

Area queries use area_ref from bcn_resolve_place:

{
  "resource_id": "d4803f9b-5f01-48d5-aeef-4ebbd76c5fd7",
  "within_place": {
    "source_resource_id": "576bc645-9481-4bc4-b8bf-f5972c20df3f",
    "row_id": 6,
    "geometry_field": "geometria_wgs84"
  },
  "fields": ["name", "addresses_neighborhood_name", "addresses_district_name"],
  "group_by": "addresses_neighborhood_name",
  "limit": 10
}

The response includes strategy, datastore_mode (sql or scan) for DataStore resources, coordinate_fields, _geo coordinates with optional distance_m, scan counts, match counts, truncation flags, upstream_total for fully upstream-filtered DataStore resources, and groups when group_by is provided. When a DataStore SQL query still needs local within_place polygon filtering, upstream_bbox_total reports the bbox-matching upstream count before exact polygon containment. When local contains filtering is applied after SQL pushdown, upstream_prefilter_total reports the upstream count before the local text filter. When within_place and contains are combined, both fields are present and report the same pre-local-filter count (i.e., bbox-matching rows that also satisfy the SQL WHERE clause). The logical_request_body.sql in provenance reflects the caller's logical query (using their limit/offset); the runtime issues paginated upstream calls behind it whenever local post-filtering is needed, so replaying the logical SQL verbatim returns bbox-matching rows, not the post-filtered slice. Group rows include count, sample, and for near queries min_distance_m plus sample_nearest.

DataStore near, bbox, and within_place queries push spatial predicates into CKAN SQL, while DataStore calls without spatial inputs and download resources still scan locally. By default, BCN geo CSV scans read the full download so late rows are not missed. If CATALUNYA_MCP_BCN_GEO_SCAN_MAX_ROWS is set and truncation_reason is scan_cap, additional matches may exist beyond the scanned rows; narrow bbox, contains, or filters, or unset the cap for trusted local runs. Download JSON resources are accepted only when small enough to parse as complete documents; larger JSON resources should use a DataStore or CSV sibling.

7. Preview Inactive CSV/JSON Resources

If datastore_active is false, use bcn_preview_resource for a bounded sample:

{
  "resource_id": "23124fd5-521f-40f8-85b8-efb1e71c2ec8",
  "limit": 5
}

Preview is intentionally not an export tool. It only follows HTTPS URLs hosted by opendata-ajuntament.barcelona.cat, validates every redirect, reads at most CATALUNYA_MCP_BCN_UPSTREAM_READ_BYTES + 1, and parses CSV/JSON into capped rows.

Query Safety

The server is deliberately defensive:

• It is read-only.

• It validates Socrata source IDs before calling upstream APIs.

• It caps returned rows with CATALUNYA_MCP_MAX_RESULTS.

• It caps response size with CATALUNYA_MCP_RESPONSE_MAX_BYTES.

• It applies request timeouts with CATALUNYA_MCP_REQUEST_TIMEOUT_MS.

• It preserves upstream error details when they help the model fix a query.

• It maps IDESCAT cell-limit errors to narrow_filters with the original JSON-stat error in source_error.

• It restricts Open Data BCN previews to allowlisted HTTPS BCN download hosts and caps upstream preview bytes.

• It reuses the same BCN download allowlist for geospatial CSV/JSON scans. Optional BCN geo scan byte/row caps can be set for constrained deployments.

If Socrata rejects a query, inspect error.message. For example, query.soql.no-such-column means the query used an invalid field. Return to socrata_describe_dataset, choose a valid field_name, and retry with a corrected clause.

Configuration

The server reads configuration from environment variables supplied by the shell or MCP client. It does not auto-load .env files; .env.example is provided as a copyable reference.

Example client configuration with environment overrides:

{
  "mcpServers": {
    "catalunya-opendata": {
      "command": "node",
      "args": ["/absolute/path/to/catalunya-opendata-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "warn",
        "CATALUNYA_MCP_MAX_RESULTS": "250",
        "SOCRATA_APP_TOKEN": "your-token"
      }
    }
  }
}

Development

Evaluations

The repository includes live MCP evaluations for checking how well the server performs as an actual MCP adapter, not just as local TypeScript modules. The evaluator builds the project, starts node dist/index.js over stdio, calls the public MCP surface, and grades each tool, prompt, and resource response with a deterministic pass/fail assertion.

Use replay mode for deterministic local or CI checks that should not depend on live upstream availability:

npm run eval:replay:canary
npm run eval:replay:stress

Replay mode reads committed cassettes from tests/fixtures/evals/. It exercises the same evaluation logic and report schema, but returns previously captured MCP responses instead of calling Socrata or IDESCAT.

Use live mode while checking current upstream behavior:

npm run canary:live
npm run eval:canary
npm run eval:stress

The GitHub Actions Live Canary workflow is manual-only. It installs dependencies, builds once, optionally runs the dedicated Socrata, IDESCAT, and BCN connector canaries, then runs the selected canary or stress MCP evaluation profile and uploads the JSON report artifact.

Refresh cassettes after intentionally changing adapter behavior or accepting upstream drift:

npm run eval:record:canary
npm run eval:record:stress

The stress profile currently runs 152 live cases:

The cases cover discovery, metadata, bounded data queries, safe BCN CSV preview, BCN resource recommendations, BCN place resolution for landmarks, streets, neighborhoods, and districts, BCN city-query planning/execution/answering, BCN answer composition for grouped, nearest, blocked, and empty answers, BCN area-aware geospatial queries, prompts, metadata resources, pagination, invalid inputs, upstream errors, local cap behavior, low-response-cap degradation, and the IDESCAT long-filter regression. In particular, the IDESCAT regression verifies long multi-value filters stay in a canonical GET URL, return request_method: "GET", omit request body params, and preserve the expected selected cell count.

Every run writes a machine-readable JSON report under tmp/, for example tmp/mcp-eval-stress-<timestamp>.json. The report includes each case id, inputs, binary score, failure reason, sub-assertions with expected and actual values, duration, compact result summary, connector totals, and expected-count checks. A run fails if any case fails or if the expected MCP/Socrata/IDESCAT case counts drift.

Live evals are intentionally separate from npm run check because they call Generalitat and IDESCAT services. If an upstream service is down or rate-limited, a live eval can fail even when local unit tests and replay evals are healthy. For more detail on the evaluation design, cassette modes, and report format, see docs/evaluations.md.

Client-facing golden answer examples for grouped, nearest, blocked, empty, and caveat-bearing BCN answers live in docs/golden-answers.md. The machine-readable answer contract lives in docs/contracts/bcn-answer-city-query.schema.json.

Release Checklist

Before opening or merging routine changes, run npm run check. This stays local and does not include live upstream canaries.

For release readiness, run npm run release:check. This includes npm run check plus npm run eval:replay:stress, so it covers typecheck, lint, unit tests, smoke output, package size budget, and the committed protocol-level stress cassette.

Before publishing a GitHub release, run npm run release:verify from the commit being released after its v<package.version> tag has been pushed. It re-runs the release gate, then checks that the worktree is clean, the branch is synced, package.json, package-lock.json, and docs/release-notes.md agree on the version, the packed package only contains dist/, README.md, LICENSE, and package.json, local and remote tags point at HEAD, GitHub Actions CI is green for HEAD, and the package's private/public npm posture is explicit. Use node scripts/release-verify.mjs --require-release after creating the GitHub release when you want a post-release confirmation.

Before publishing a package, run npm pack --dry-run, confirm the tarball includes only dist/, README.md, LICENSE, and package.json, and confirm dist/index.js is executable with test -x dist/index.js. The package budget remains enforced by npm run package:size; current limits are 512 KiB packed, 8 MiB unpacked, 5 MiB source IDESCAT index, and 7 MiB built IDESCAT index.

For adapter changes that may need fresh live evidence, optionally run npm run canary:live, npm run eval:stress, and, when accepting upstream drift or intentional adapter changes, npm run eval:record:stress. These commands exercise the public MCP surface against live Generalitat/IDESCAT/Open Data BCN services, so they are intentionally manual and may fail when an upstream service is unavailable. The GitHub Actions Live Canary workflow can also be started manually with either the canary or stress evaluation profile. The evaluation harness writes a JSON report with binary case scores and connector-level summaries; see docs/evaluations.md. User-facing release notes live in docs/release-notes.md.

Operational release and upstream-incident guidance lives in docs/operations.md. Install-from-tarball smoke guidance lives in docs/install-smoke.md.

Project Notes

The current implementation is intentionally small: one transport and three source adapters (Socrata catalog/query, IDESCAT Tables v2 browse/metadata/data, and Open Data BCN catalog/query/place/geo workflows). The IDESCAT search index ships as committed generated source; refresh it manually with npm run refresh:idescat when the upstream catalog changes. Broader architecture notes live in specs.md, but the README documents what the repository does today.

License

MIT. See LICENSE.