dane-gov-pl-mcp 0.1.0

MCP server for dane.gov.pl API

Dane.gov.pl MCP Server

A Model Context Protocol (MCP) Server that integrates with dane.gov.pl, Poland's central open data portal. This server acts as a bridge between Polish public datasets and modern AI applications, creating a transparent, fast, and structured API layer consumable by LLMs, agents, and intelligent services.

Inspired by the success of data-gov-il-mcp, this project aims to unlock the potential of Polish government data for AI-powered civic applications.

🎯 Project Vision

We are building the first MCP server for Polish open government data. No equivalent exists today, making this a strategic opportunity to position Poland at the forefront of civic tech and AI infrastructure.

The Problem

• Poland's <dane.gov.pl> has rich datasets but poor accessibility for AI models
• Inconsistent data formats and lack of clear APIs
• No standardized way for LLMs to access Polish government data

The Solution

An open-source MCP Server that:

• 🔍 Discovers datasets through semantic search and filtering
• 🔄 Parses diverse data formats into unified structures
• 🧠 Processes data with LLM-powered operations
• 📊 Visualizes results through chart integrations
• ⚡ Aggregates large datasets using Polars for performance

🚀 Current State

The project is in its final stages of development. All core functionality is implemented and tested, with ongoing quality-of-life improvements and bug fixes being made:

✅ Available Features

• Institution Search - Find and filter government institutions by name, city, description
• Dataset Discovery - Search datasets by keywords, titles, and descriptions
• Resource Listing - Browse individual data files within datasets
• Showcases Search - Find real-world visualizations and applications that use the datasets
• Metadata Access - Get detailed information about institutions, datasets, and resources
• Data Parsing - Convert resources into LLM-ready Markdown documents
• LLM Processing - Enable grouping, aggregating, filtering, and sorting operations for tabular data resources (loaded into Polars DataFrames)
• Chart Integration - Visualize processed data through MCP chart tools

🏗️ Architecture

The system comprises three distinct functionality layers:

┌─────────────────┐
│    Discovery    │  ← Search & filter datasets/resources/institutions/showcases
├─────────────────┤
│     Parsing     │  ← Convert resources LLM ready Markdown documents 
├─────────────────┤
│   Processing    │  ← LLM-powered operations on Polars dataframes
└─────────────────┘

Discovery Layer

• Search datasets by keywords (e.g., "water condition")
• Filter institutions by city, name, or description
• Browse resources within selected datasets
• Access comprehensive metadata

Parsing Layer

• Convert CSV, JSON, XLSX, PDF and other files to Markdown documents
• Support for most of the resources in optimal formats

Processing Layer

• Data operations (group, filter, aggregate)
• Integration with visualization tools

🛠️ Tech Stack

• Python - Core development language
• FastMCP - MCP server framework
• Pydantic - Data validation and serialization
• Polars - High-performance data processing
• Unstructured - Document parsing and extraction for PDFs, CSVs and other formats
• Fly.io - Deployment platform

🚀 Installation & Setup

Prerequisites

• Python 3.11+
• UV package manager (recommended)

Quick Start

# Clone the repository
git clone https://github.com/appunite/dane-gov-pl-mcp.git
cd dane-gov-pl-mcp

# Install dependencies
uv sync

# Run the MCP server
uv run python -m src.app --transport stdio

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor):

{
  "mcpServers": {
    "dane-gov-pl-mcp": {
      "command": "/path/to/dane-gov-pl-mcp/.venv/bin/python",
      "args": ["-m", "src.app", "--transport", "stdio"],
      "cwd": "/path/to/dane-gov-pl-mcp",
      "env": {
        "PYTHONPATH": "/path/to/dane-gov-pl-mcp",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

📖 Usage Examples

Discovery

# Search datasets by keywords
search_datasets(search_filters={"query_all": "environment"})

# Find institutions by location
search_institutions(search_filters={"city_terms": "Warszawa"})

# Get dataset details
get_resources_details(dataset_ids=[123, 456])

Document Parsing

# Parse files to Markdown
get_file_content(resource_ids=[123, 456])

Tabular Data Processing

# Get resource metadata
get_tabular_resource_metadata(resource_ids=[123])

# Query tabular data
get_tabular_data(resource_id=123, search_filters={"q": "col1:Warszawa"})

# Advanced DataFrame operations
resource_to_dataframe(resource_id=123, dataframe_operations={
    "primary_group": "col1",
    "aggregations": ["sum", "mean"],
    "aggregation_columns": ["col2", "col2"],
    "sort_columns"=["col2_sum", "col1"], 
    "sort_descending"=[True, False]
})

🤝 Contributing

We welcome contributions! This project aims to make Polish government data more accessible and usable for everyone.

Contributing Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🔗 Links

• dane.gov.pl - Poland's Open Data Portal
• API Documentation - Official API docs
• Technical Standard - Data standards

Authors

Dane-gov-pl-mcp is created by Appunite.

Since 2010, Appunite is a collective of software engineers, product builders, and problem solvers. We partner with bold teams to tackle product and business challenges—designing custom-built squads that ship fast and think strategically. From AI-enabled workflows to mobile platforms and cloud-native systems, we deliver end-to-end execution with full accountability.

Looking for your unfair advantage in tech execution? Talk to us.

Copyright 2025, Appunite

Licensed under the MIT License