convez.ai
MCP ServerDados & AnalyticsIntermediário
cfdude

Data Commons MCP Server

cfdude/datacommons-mcp

Acesso estruturado a dados públicos estatísticos via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para acesso a dados estatísticos públicos do Data Commons, um repositório aberto de conhecimento com múltiplos datasets integrados. Permite que agentes e clientes Claude consultem o grafo de conhecimento de forma estruturada, com suporte a instâncias customizadas, exportação em CSV e streaming de grandes volumes.

Instalação

$npx convez-ai cfdude/datacommons-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 dias
Versão
—
Issues abertas
1
Contribuidores
2

Casos de uso

  • Consultas de dados econômicos, demográficos e sociais para análises
  • Construção de relatórios automatizados com dados públicos verificados
  • Integração de estatísticas públicas em aplicações de IA

Veredito

Ferramenta sólida para acesso a dados públicos em escala, bem integrada ao protocolo MCP e com bom suporte a grandes volumes. Exige API key e configuração inicial, mas oferece flexibilidade real para consultas estatísticas estruturadas.

README

A tradução para o português deste README ainda está na fila.

Data Commons MCP Server

This is a Model Context Protocol (MCP) server for fetching public statistical data from Data Commons instances.

Data Commons is an open knowledge repository that provides a unified view across multiple public data sets and statistics. This server allows any MCP-enabled agent or client to query the Data Commons knowledge graph.

Features

  • MCP-Compliant: Implements the Model Context Protocol for seamless agent integration.
  • Data Commons Access: Fetches public statistics and data from the base datacommons.org knowledge graph.
  • Custom Instance Support: Can be configured to work with Custom Data Commons instances.
  • Flexible Serving: Runs over both streamable HTTP and stdio.
  • Large Dataset Handling: Automatic pagination and streaming for large observation queries.
  • Multiple Output Modes: Choose between screen display, automatic CSV export, or forced file output.
  • Multi-File Export: Split large exports by place, place type, date, or chunk size.
  • Data Lineage: CSV exports include comprehensive lineage headers for data provenance.
  • Progress Streaming: Real-time progress updates via STDIO or SSE transport.

Quickstart

Prerequisites

  1. You must have a Data Commons API key; create one at apikeys.datacommons.org.
  2. Install uv by following the official installation instructions.

Configuration

Set the following required environment variable in your shell:

export DC_API_KEY=<your API key>

Start the server

Run the server from your command line in one of two modes:

Streamable HTTP

This runs the server with Streamable HTTP.

# Runs on default port 8080
uvx datacommons-mcp serve http [--port <PORT>]

The server will be available at http://localhost:<port>/mcp.

stdio

This transport mode is intended for local integrations and is programmatically configured within a client (like Gemini CLI settings) to communicate over stdio.

uvx datacommons-mcp serve stdio

Clients

You can use any MCP-enabled agent or client to connect to your running server. For example, see the Data Commons MCP documentation for guides on connecting:

Or see your preferred client's documentation for how to configure it, using the commands listed above.

Advanced Configuration

Server Options

HTTP Mode Options

uvx datacommons-mcp serve http [OPTIONS]
OptionDefaultDescription
--port8080Port to run the HTTP server on
--progress-transportstdioTransport for progress updates (stdio or sse)
--verbosefalseEnable verbose progress logging
--sse-port8081Port for SSE progress server (when using SSE transport)
--storage-dir./datacommons-dataDirectory for exported data files

stdio Mode Options

uvx datacommons-mcp serve stdio [OPTIONS]
OptionDefaultDescription
--verbosefalseEnable verbose progress logging
--storage-dir./datacommons-dataDirectory for exported data files

Large Dataset Handling

The server automatically handles large datasets through pagination-based streaming and row count thresholds:

  1. Auto Mode (default): Automatically detects large datasets and streams them to CSV files. File mode is triggered when:
    • The API returns multiple pages (pagination detected), OR
    • The response exceeds the row threshold (default: 500 rows)
  2. Screen Mode: Forces all results to screen (use with caution for large datasets).
  3. File Mode: Forces all results to CSV file, even for small datasets.

The row threshold prevents large single-page responses from flooding the context window. Configure it via DC_SCREEN_ROW_THRESHOLD environment variable.

Output files are saved to a configurable storage directory (default: ./datacommons-data) with timestamped filenames. Configure the storage directory via the --storage-dir CLI option or DC_STORAGE_DIR environment variable.

Multi-File Export

For very large datasets, you can split exports into multiple files using different strategies:

StrategyDescription
by_placeOne file per unique place DCID
by_place_typeOne file per place type (State, County, etc.)
by_dateOne file per year
by_chunkFixed number of rows per file

Each multi-file export includes a manifest JSON file describing all exported files.

Data Lineage Headers

CSV exports include comprehensive lineage headers as comments at the top of each file:

# ============================================================
# Data Commons MCP Server Export
# ============================================================
# Query:
#   variable_dcid: Count_Person
#   variable_name: Total Population
#   place_dcid: country/USA
#   child_place_type: State
# Date Filter:
#   date_filter: range
#   date_range_start: 2019-01-01
#   date_range_end: 2021-12-31
# Source:
#   source_id: CensusACS5YearSurvey
#   source_url: https://data.census.gov
# Export:
#   server_version: 1.2.0
#   timestamp: 2024-01-15T10:30:00Z
#   total_pages: 5
# ============================================================
#
place_dcid,place_name,place_type,variable_dcid,variable_name,date,value,source_id
...

To disable lineage headers, set include_lineage=False in the configuration.

Progress Streaming

The server supports real-time progress updates during large data fetches:

STDIO Transport (default) Progress messages are written to stderr in JSON format, suitable for programmatic parsing.

SSE Transport For web-based clients, progress can be streamed via Server-Sent Events:

uvx datacommons-mcp serve http --progress-transport sse --sse-port 8081

Connect to http://localhost:8081/events to receive real-time progress updates.

Environment Variables

VariableRequiredDescription
DC_API_KEYYesYour Data Commons API key
DC_API_ROOTNoCustom API root URL
DC_WEBSITE_ROOTNoCustom website root URL
DC_STORAGE_DIRNoDirectory for storing exported data files (default: ./datacommons-data)
DC_OUTPUT_FORMATNoDefault format for file exports: csv or json (default: csv)
DC_MAX_PAGESNoMaximum pages to fetch in paginated requests (default: 100)
DC_INCLUDE_LINEAGENoInclude data lineage headers in CSV exports (default: true)
DC_MULTI_FILE_EXPORTNoEnable multi-file export with companion CSVs (default: false)
DC_SCREEN_ROW_THRESHOLDNoMax rows to return to screen in auto mode; larger responses go to file (default: 500)

Using MCP Tools with a Custom Data Commons

Follow the Guide for using MCP Tools with Custom Data Commons to set additional environment variables required for custom configuration.

Version History

v1.2.0

  • Added pagination-based streaming for large datasets
  • Added automatic CSV export for multi-page responses
  • Added output mode selection (auto, screen, file)
  • Added transport abstraction layer (STDIO, SSE)
  • Added SSE server for real-time progress streaming
  • Added multi-file export with split strategies
  • Added comprehensive data lineage headers to CSV exports

v1.1.x

  • Initial release with core MCP functionality
  • Search indicators and get observations tools
  • Custom Data Commons support
Ver o original no GitHub

Bom para

Relacionados