ARJ999/Data-Commons-mcp-server

Data Commons MCP Server

A fully functional Model Context Protocol (MCP) server for accessing public statistical data from Data Commons. This server is optimized for deployment on Railway.app and can be accessed remotely by MCP clients like Manus, Claude Desktop, and other MCP-enabled applications.

Overview

Data Commons is an open knowledge repository providing a unified view across multiple public datasets and statistics. This MCP server enables AI agents and applications to query the Data Commons knowledge graph through a standardized protocol.

Key Features

• MCP-Compliant: Implements the Model Context Protocol for seamless agent integration
• Data Commons Access: Fetches public statistics from the datacommons.org knowledge graph
• Custom Instance Support: Can be configured to work with custom Data Commons instances
• Railway-Ready: Pre-configured for one-click deployment on Railway.app
• Remote Access: Accessible via HTTP for remote MCP clients
• Comprehensive Tools: Includes tools for searching indicators and fetching observations

Architecture

The server provides two main MCP tools:

1. search_indicators: Search and discover statistical variables (indicators) available in Data Commons
2. get_observations: Fetch actual statistical data for specific variables and places

Quick Start

Prerequisites

1. Data Commons API Key: Create one at apikeys.datacommons.org
2. Python 3.11+: Required for local development
3. Railway Account: For deployment (optional)

Local Development

1. Clone the repository:

   git clone https://github.com/ARJ999/Data-Commons-mcp-server.git
   cd Data-Commons-mcp-server
   

2. Set up environment:

   cp .env.example .env
   # Edit .env and add your DC_API_KEY
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the server:

   python -m datacommons_mcp.cli serve http --host 0.0.0.0 --port 8080
   

5. Access the MCP endpoint:

   http://localhost:8080/mcp
   

Railway Deployment

One-Click Deploy

Manual Deployment

1. Create a new Railway project:

   • Go to railway.app
   • Click "New Project" → "Deploy from GitHub repo"
   • Select this repository

2. Configure environment variables:

   • Add DC_API_KEY with your Data Commons API key
   • Railway automatically sets PORT

3. Deploy:

   • Railway will automatically detect the configuration and deploy
   • Your MCP server will be available at: https://your-app.railway.app/mcp

Environment Variables

Using with MCP Clients

Manus

Configure Manus to connect to your deployed MCP server:

{
  "mcpServers": {
    "datacommons": {
      "url": "https://your-app.railway.app/mcp",
      "transport": "http"
    }
  }
}

Claude Desktop

Add to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "datacommons": {
      "command": "curl",
      "args": ["-X", "POST", "https://your-app.railway.app/mcp"]
    }
  }
}

Other MCP Clients

Any MCP-enabled client can connect using the HTTP endpoint:

• Endpoint: https://your-app.railway.app/mcp
• Transport: Streamable HTTP
• Protocol: MCP (Model Context Protocol)

Available Tools

1. search_indicators

Search for statistical variables (indicators) in Data Commons.

Parameters:

• query (string): Natural language search query
• place_dcids (list, optional): Filter by specific place DCIDs
• topic_dcids (list, optional): Filter by topic DCIDs

Example:

search_indicators(
    query="population growth rate",
    place_dcids=["country/USA"]
)

2. get_observations

Fetch statistical observations for a variable and place.

Parameters:

• variable_dcid (string): Variable identifier from search_indicators
• place_dcid (string): Place identifier
• child_place_type (string, optional): Get data for child places
• date (string, optional): Date filter ('latest', 'all', or specific date)
• date_range_start (string, optional): Start of date range
• date_range_end (string, optional): End of date range

Example:

get_observations(
    variable_dcid="Count_Person",
    place_dcid="country/USA",
    date="latest"
)

Project Structure

Data-Commons-mcp-server/
├── datacommons_mcp/          # Main package
│   ├── __init__.py
│   ├── server.py             # MCP server implementation
│   ├── cli.py                # Command-line interface
│   ├── clients.py            # Data Commons API client
│   ├── services.py           # Business logic
│   ├── settings.py           # Configuration
│   ├── data_models/          # Pydantic models
│   └── ...
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Project metadata
├── Procfile                 # Railway start command
├── railway.json             # Railway configuration
├── runtime.txt              # Python version
├── .env.example             # Environment template
├── .gitignore              # Git ignore rules
└── README.md               # This file

Technical Details

Dependencies

• FastAPI: Web framework for HTTP server
• FastMCP: MCP protocol implementation
• Uvicorn: ASGI server
• datacommons-client: Official Data Commons Python client
• Pydantic: Data validation and settings management

Transport Modes

The server supports two transport modes:

1. Streamable HTTP (default for Railway):

   • Accessible via HTTP/HTTPS
   • Suitable for remote clients
   • Endpoint: /mcp

2. stdio (for local integrations):

   • Communicates via standard input/output
   • Used by local MCP clients like Gemini CLI

Troubleshooting

Server won't start

• Check API Key: Ensure DC_API_KEY is set correctly
• Check Python Version: Must be 3.11 or 3.12
• Check Dependencies: Run pip install -r requirements.txt

Can't connect from MCP client

• Verify URL: Ensure you're using the correct Railway URL
• Check Endpoint: URL should end with /mcp
• Check Deployment: Verify the Railway deployment is successful

API Errors

• Invalid API Key: Get a new key from apikeys.datacommons.org
• Rate Limits: Data Commons may have rate limits; check their documentation

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is based on the Data Commons Agent Toolkit and is licensed under the Apache License 2.0.

Resources

• Data Commons: datacommons.org
• MCP Specification: Model Context Protocol
• Railway Documentation: docs.railway.app
• Original Repository: datacommonsorg/agent-toolkit

Support

For issues related to:

• This deployment: Open an issue on this repository
• Data Commons API: Visit datacommons.org/support
• Railway platform: Check Railway documentation

Built with ❤️ for the MCP ecosystem