Content
# 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](https://www.npmjs.com/package/@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:
```bash
# 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:
```bash
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](https://www-genesis.destatis.de/datenbank/online/) 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](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:
```bash
npm install
```
or
```bash
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:
```bash
npm run build
npm start
```
Or in development mode:
```bash
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
```json
{
"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
```json
{
"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:
```typescript
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.
