Documentation

Use Subsets with MCP clients or integrate directly with our REST API

MCP Server

Subsets provides a Model Context Protocol (MCP) server that enables AI assistants to search and query statistical data directly. Use with your favorite MCP client, like Claude Desktop.

⚙️Installation & Setup

1. Get your API key

First, sign up at subsets.io to get your API key.

2. Configure Your MCP Client

For Claude Desktop, add Subsets to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

JSON

{
  "mcpServers": {
    "subsets": {
      "command": "npx",
      "args": ["@subsetsio/mcp-server", "--api-key", "YOUR_KEY"],
      "env": {}
    }
  }
}

3. Restart Your MCP Client

Restart your MCP client (e.g., Claude Desktop). You should see the Subsets tools available in the tools menu.

🛠️Available MCP Tools

search_datasets—Find relevant statistical datasets

UsesGET /datasets

Input Schema

q: string - Search query for semantic search
limit: integer - Maximum results (1-100, default: 10)
offset: integer - Number of results to skip (default: 0)
min_score: number - Minimum relevance score (0-2, optional)

Example Output

JSON

{
  "total": 3,
  "datasets": [
    {
      "id": "eurostat_unemployment_2024",
      "title": "European Unemployment Rates 2024",
      "description": "Monthly unemployment rates for EU countries",
      "license": "CC-BY-4.0",
      "columns": [
        {"id": "country", "type": "string", "description": "Country code"},
        {"id": "rate", "type": "double", "description": "Unemployment rate"}
      ],
      "score": 1.85,
      "match_type": "dataset"
    }
  ]
}

get_dataset_details—Get schema and metadata for a specific dataset

UsesGET /datasets/{dataset_id}

Input Schema

dataset_id: string - Dataset identifier (required)

Example Output

JSON

{
  "id": "eurostat_unemployment_2024",
  "title": "European Unemployment Rates 2024",
  "description": "Monthly unemployment rates for EU countries",
  "license": "CC-BY-4.0",
  "source_id": "eurostat",
  "columns": [
    {
      "id": "country",
      "description": "ISO 3166-1 alpha-2 country code",
      "type": "string",
      "nullable": false,
      "unique": false
    },
    {
      "id": "year",
      "description": "Year of measurement",
      "type": "integer",
      "nullable": false,
      "unique": false
    },
    {
      "id": "rate",
      "description": "Unemployment rate as percentage",
      "type": "double",
      "nullable": true,
      "unique": false
    }
  ]
}

execute_sql_query—Run SQL queries on available datasets

UsesPOST /sql/query

Input Schema

query: string - SQL query to execute (SELECT only, required)

Example Output

JSON

{
  "data": [
    {"country": "ES", "rate": 11.2},
    {"country": "GR", "rate": 9.8},
    {"country": "IT", "rate": 7.5}
  ]
}