Syndicats/destatis-genesis-mcp

GENESIS API MCP Server (Unofficial)

DISCLAIMER: This is an UNOFFICIAL project and is not affiliated with, endorsed by, or connected to the German Federal Statistical Office (Statistisches Bundesamt/Destatis) in any way. This is an independent implementation that uses the publicly available GENESIS API.

A Model Context Protocol (MCP) server for accessing statistical data from the GENESIS API provided by Destatis (Federal Statistical Office of Germany).

Overview

This MCP server provides agent-centric tools for interacting with the GENESIS API, allowing AI agents to search, retrieve, and analyze statistical data from the German Federal Statistical Office. The server abstracts away HTTP details, authentication, and complex IDs to provide a clean, composable interface for AI agents.

Note on Functionality: While we strive to provide reliable access to the GENESIS API, this project is maintained by independent developers and is provided as-is without any warranties or guarantees regarding functionality, accuracy, or availability. The GENESIS API itself may change without notice, which could affect the operation of this MCP server. Users are encouraged to report issues and contribute improvements.

The server is built using the official @modelcontextprotocol/sdk package, which provides the infrastructure for creating and registering MCP tools.

Installation

Option 1: Using npm package (recommended)

You can use this MCP server directly from npm without cloning the repository:

# Run directly with npx (no installation required)
npx @syndicats/destatis-genesis-mcp

# Or install globally
npm install -g @syndicats/destatis-genesis-mcp
destatis-genesis-mcp

To configure the server with your GENESIS API credentials when using npx, you can set environment variables:

GENESIS_API_TOKEN=your_token npx @syndicats/destatis-genesis-mcp

Option 2: From source

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

Obtaining a GENESIS API Token

To use this MCP server, you'll need to obtain an API token from the GENESIS database:

1. Visit the GENESIS Online Database and create a free account if you don't have one already
2. Log in to your account
3. Navigate to the API settings page at https://www-genesis.destatis.de/datenbank/online#modal=web-service-api
4. Your API token will be displayed on this page
5. Copy this token for use in the configuration

Installation

1. Clone the repository
2. Install dependencies:

   npm install
   

   or

   yarn install
   

3. Create a .env file based on .env.example and fill in your GENESIS API credentials:

   GENESIS_API_URL=https://www-genesis.destatis.de/genesisWS/rest/2020
   GENESIS_LANGUAGE=de  # 'de' or 'en'
   
   # Authentication (use either username/password OR API token)
   GENESIS_USERNAME=YOUR_USERNAME
   GENESIS_PASSWORD=YOUR_PASSWORD
   GENESIS_API_TOKEN=YOUR_API_TOKEN  # Alternative to username/password
   

Running the Server

Build and start the server:

npm run build
npm start

Or in development mode:

npm run dev

The server will start on port 3000 by default. You can change this by setting the PORT environment variable.

Configuring in an MCP Client Application

To use this MCP server in an MCP client application like Windsurf, you have two options:

Option 1: Using the npm package

{ 
  "mcpServers": {
    "destatis-genesis-mcp": {
      "command": "npx",
      "args": [
        "@syndicats/destatis-genesis-mcp"
      ],
      "env": {
        "GENESIS_API_URL": "https://www-genesis.destatis.de/genesisWS/rest/2020",
        "GENESIS_LANGUAGE": "de",
        "GENESIS_API_TOKEN": "<YOUR-API-TOKEN>"
      }
    }
  }
}

Option 2: Using a local build

{ 
  "mcpServers": {
    "destatis-genesis-mcp": {
      "command": "node",
      "args": [
        "/<local-path-to-current-project>/dist/index.js"
      ],
      "env": {
        "GENESIS_API_URL": "https://www-genesis.destatis.de/genesisWS/rest/2020",
        "GENESIS_LANGUAGE": "de",
        "GENESIS_API_TOKEN": "<YOUR-API-TOKEN>"
      }
    }
  }
}

Available Tools

The MCP server exposes the following tools for interacting with the GENESIS API:

Search Tools

• search_statistical_data: Search for statistical data in the GENESIS database using keywords. Returns matching tables, statistics, data cubes, variables, and time series.

Metadata Tools

• get_metadata_for_cube: Retrieve detailed metadata about a specific data cube.
• get_metadata_for_table: Retrieve detailed metadata about a specific statistical table.
• get_metadata_for_timeseries: Retrieve detailed metadata about a specific time series.

Data Tools

• get_dataset_data: Retrieve raw data directly from tables, cubes, or time series.
• generate_chart: Generate chart visualizations from statistical datasets.

Listing Tools

• list_cubes: List available data cubes, optionally filtered by a pattern.
• list_tables: List available statistical tables, optionally filtered by a pattern.
• list_timeseries: List available time series, optionally filtered by a pattern.
• list_statistics: List available statistics, optionally filtered by a pattern.

Tool Details

search_statistical_data

Searches for statistical data in the GENESIS database using keywords.

Parameters:

• query (string, required): Search term or keyword to find statistical data
• category (string, optional): Category of data to search for (default: all)
  • Options: 'all', 'tables', 'statistics', 'cubes', 'variables', 'time-series'
• maxResults (integer, optional): Maximum number of results to return (default: 100, max: 25000)

Returns:

• Search results including code, title, type, and additional metadata for each item

get_metadata_for_cube

Retrieves detailed metadata about a specific data cube.

Parameters:

• cubeId (string, required): ID of the data cube to retrieve metadata for
• area (string, optional): Area where the cube is stored (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'

Returns:

• Detailed metadata about the cube including title, state, time range, and raw metadata

get_metadata_for_table

Retrieves detailed metadata about a specific statistical table.

Parameters:

• tableId (string, required): ID of the statistical table to retrieve metadata for
• area (string, optional): Area where the table is stored (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'

Returns:

• Detailed metadata about the table including title, state, time range, and raw metadata

get_metadata_for_timeseries

Retrieves detailed metadata about a specific time series.

Parameters:

• timeseriesId (string, required): ID of the time series to retrieve metadata for
• area (string, optional): Area where the time series is stored (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'

Returns:

• Detailed metadata about the time series including title, state, time range, and raw metadata

list_cubes

Lists available data cubes from the GENESIS database.

Parameters:

• filter (string, optional): Filter pattern for cube IDs, supports * as wildcard (e.g., "12411*")
• area (string, optional): Area where to search for cubes (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'
• maxResults (integer, optional): Maximum number of results to return (default: 100, max: 25000)

Returns:

• List of cubes matching the filter criteria

list_tables

Lists available statistical tables from the GENESIS database.

Parameters:

• filter (string, optional): Filter pattern for table IDs, supports * as wildcard (e.g., "12411*")
• area (string, optional): Area where to search for tables (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'
• maxResults (integer, optional): Maximum number of results to return (default: 100, max: 25000)

Returns:

• List of tables matching the filter criteria

list_timeseries

Lists available time series from the GENESIS database.

Parameters:

• filter (string, optional): Filter pattern for time series IDs, supports * as wildcard (e.g., "12411*")
• area (string, optional): Area where to search for time series (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'
• maxResults (integer, optional): Maximum number of results to return (default: 100, max: 25000)

Returns:

• List of time series matching the filter criteria

get_dataset_data

Retrieves raw data directly from tables, cubes, or time series in the GENESIS database.

Parameters:

• datasetCode (string, required): The unique identifier of the dataset to retrieve (e.g., "12411-0014" for a table)
• format (string, optional): The format of the data to retrieve (default: json)
  • Options: 'json', 'csv'
• filters (object, optional): A dictionary of filters to apply to the data (e.g., {"region": "Bayern", "gender": "female"})
• startYear (integer, optional): The first year of data to include
• endYear (integer, optional): The last year of data to include

Returns:

• The raw dataset in the requested format (JSON or CSV)

generate_chart

Generates chart visualizations from statistical datasets.

Parameters:

• datasetCode (string, required): The unique identifier of the dataset to visualize (e.g., "12411-0014")
• chartType (string, required): The type of chart to generate
  • Options: 'line', 'bar', 'pie'
• filters (object, optional): A dictionary of filters to apply to the data (e.g., {"region": "Bayern", "gender": "female"})
• startYear (integer, optional): The first year of data to include
• endYear (integer, optional): The last year of data to include
• showTopValues (boolean, optional): Whether to highlight the top values in the chart
• focus (boolean, optional): Whether to focus on the data (removes padding)
• drawPoints (boolean, optional): Whether to draw points on line charts
• zoom (integer, optional): Zoom level for the chart (1-5)

Returns:

• A chart visualization as an image

list_statistics

Lists available statistics from the GENESIS database.

Parameters:

• filter (string, optional): Filter pattern for statistic IDs, supports * as wildcard (e.g., "12*")
• area (string, optional): Area where to search for statistics (default: free)
  • Options: 'free', 'all', 'public', 'user', 'group', 'office'
• maxResults (integer, optional): Maximum number of results to return (default: 100, max: 25000)

Returns:

• List of statistics matching the filter criteria

Development

Project Structure

• src/index.ts: Main entry point for the MCP server
• src/tools/: Individual MCP tool implementations
• src/services/: Service layer for interacting with the GENESIS API
• src/types/: TypeScript type definitions
• src/utils/: Utility functions

Adding New Tools

To add a new tool:

1. Create a new file in the src/tools/ directory
2. Export a function that takes the server and apiService as arguments
3. Register the tool using server.tool(name, paramsSchema, handler) method
4. Import and call the function in src/index.ts

Example:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { GenesisApiService } from '../services/genesis-api-service.js';
import { z } from 'zod';

export const myNewTool = (server: McpServer, apiService: GenesisApiService): void => {
  // Define parameter schema using Zod
  const paramsSchema = {
    param1: z.string().describe('Description of parameter 1'),
    param2: z.number().describe('Description of parameter 2').optional()
  };

  // Register the tool with the MCP server
  server.tool(
    'my_new_tool',
    paramsSchema,
    /**
     * Tool description goes here
     */
    async (args: { param1: string; param2?: number }, _extra: any) => {
      // Tool implementation
      const result = await apiService.get('/some/endpoint', { /* params */ });
      
      // Return results in the format expected by the MCP SDK
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
      };
    }
  );
};

License

This project is licensed under the MIT License.