eurostat-mcp-server

Query Eurostat Dataframes

eurostat_dataframe_query

Read-onlyIdempotent

Run a read-only SQL SELECT against tables staged on a Eurostat dataframe canvas — the way to reach observations past the 5,000-row inline cap of eurostat_query_dataset and past the inline preview of a eurostat_download_dataset bulk download, and to aggregate, group, or join across staged tables without re-fetching from Eurostat. Call eurostat_dataframe_describe first for the table and column names, which differ between the tools that stage them. Only a single SELECT statement runs: statement chaining, non-SELECT verbs, and functions that read files or external data are rejected. Columns are flat — every dimension is a code column named after the dimension, the measure is obs_value, the observation flag is obs_flag / obs_flag_label and the confidentiality marker is conf_status / conf_status_label; a "_label" companion per dimension exists only on tables eurostat_query_dataset staged. Both observation stagers write the same five measure columns with the same codes, so join their tables on dimension codes and time and compare obs_flag or conf_status across them directly; a DS-* table also carries obs_value_text, a value published as text (e.g. a PRODCOM unit "KG"). A value list eurostat_get_dimension_values staged has two columns, code and label: join it to the code column of a download (e.g. JOIN df_x g ON d.geo = g.code) to label that table.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sql`	Yes	A single read-only SELECT statement. Reference tables by the names eurostat_dataframe_describe reports. Example: SELECT geo, geo_label, AVG(obs_value) AS mean FROM df_a1b2c3d4 WHERE time >= '2020' GROUP BY geo, geo_label ORDER BY mean DESC.
`canvas_id`	Yes	Canvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables.

Output Schema

TableJSON Schema

Name	Required	Description
`rows`	No	Result rows, each keyed by column name. Bounded by the canvas row limit. 64-bit integer results — COUNT(*) among them — arrive as strings so values outside the JSON number range survive intact; cast to DOUBLE in the SQL if a number is wanted.
`error`	No	Present when the call failed. Absent on success.
`columns`	No	Column names in projection order.
`canvasId`	No	Canvas identifier the query ran against.
`rowCount`	No	Rows materialized into this response. Equals the full result size unless truncated is true.
`truncated`	No	True when the result exceeded the canvas row limit and was cut short. Add a LIMIT, an aggregate, or a narrower WHERE clause to see the rest.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 25, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas identifier returned as canvasId by eurostat_query_dataset or eurostat_download_dataset. Identifies the workspace holding the staged tables."New value: +"Canvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables."

Changed2 schema fields changedSep 22, 2026
- removedInput schema / properties / canvas_id / minLength
```
Removed value: -1
```
- addedInput schema / properties / canvas_id / pattern
```
Added value: +"^[A-Za-z0-9_-]{10}$"
```

Changed6 schema fields changedAug 21, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "canvasId",
+      "columns",
+      "rows",
+      "rowCount",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `canvas_disabled`: This deployment runs without a dataframe canvas, so there is nothing to query. `canvas_not_found`: The canvas_id is unknown or its lifetime has elapsed. `missing_table`: The SQL names a table that is not staged on this canvas, or that has expired. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "canvas_disabled",
+            "canvas_not_found",
+            "missing_table"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "canvasId",
-  "columns",
-  "rows",
-  "rowCount",
-  "truncated"
-]

Changed1 schema field changedAug 4, 2026

changedInput schema / properties / canvas_id / description

Previous value: -"Canvas identifier returned by eurostat_query_dataset as canvasId. Identifies the workspace holding the staged tables."New value: +"Canvas identifier returned as canvasId by eurostat_query_dataset or eurostat_download_dataset. Identifies the workspace holding the staged tables."

AddedAug 4, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral traits: statement chaining and non-SELECT verbs are rejected, columns are flat with specific names, and the measure/observation/confidentiality columns are standardized across stagers. This gives the agent a detailed model of how queries will behave and what data shape to expect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense and fairly long, but every sentence carries operational information needed to invoke the tool correctly. It is front-loaded with purpose and constraints, and the later detail about column layouts and join semantics is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of annotations and an output schema, the description is remarkably complete. It covers prerequisites (call dataframe_describe first), query restrictions, table schemas, cross-stager join semantics, and the value-list helper table, so an agent has enough context to both select and correctly invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that SQL must be a single SELECT, that table names come from dataframe_describe and differ by stager, and how to join dimension value tables. This goes beyond repeating the schema fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: run a read-only SQL SELECT against staged Eurostat dataframe tables. It clearly differentiates the tool from siblings by naming the capabilities it alone provides, such as exceeding the 5,000-row cap of eurostat_query_dataset and aggregating/joining staged tables without re-fetching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly identifies when to use this tool versus alternatives: to get past the 5,000-row cap, past download previews, and to aggregate, group, or join staged data. It also instructs calling eurostat_dataframe_describe first and states the hard constraint that only a single SELECT statement is allowed, giving clear operational guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All eurostat-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.