# Data Commons MCP Server

A fully functional **Model Context Protocol (MCP)** server for accessing public statistical data from [Data Commons](https://datacommons.org). 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](https://apikeys.datacommons.org/)
2. **Python 3.11+**: Required for local development
3. **Railway Account**: For deployment (optional)

### Local Development

1. **Clone the repository**:
   ```bash
   git clone https://github.com/ARJ999/Data-Commons-mcp-server.git
   cd Data-Commons-mcp-server
   ```

2. **Set up environment**:
   ```bash
   cp .env.example .env
   # Edit .env and add your DC_API_KEY
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Run the server**:
   ```bash
   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

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template)

### Manual Deployment

1. **Create a new Railway project**:
   - Go to [railway.app](https://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

| Variable | Required | Description |
|----------|----------|-------------|
| `DC_API_KEY` | Yes | Your Data Commons API key from [apikeys.datacommons.org](https://apikeys.datacommons.org/) |
| `DC_API_ROOT` | No | Custom Data Commons instance URL (defaults to datacommons.org) |
| `PORT` | No | Server port (Railway sets this automatically) |

## Using with MCP Clients

### Manus

Configure Manus to connect to your deployed MCP server:

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

### Claude Desktop

Add to your Claude Desktop MCP settings:

```json
{
  "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**:
```python
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**:
```python
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](https://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](https://github.com/datacommonsorg/agent-toolkit) and is licensed under the Apache License 2.0.

## Resources

- **Data Commons**: [datacommons.org](https://datacommons.org)
- **MCP Specification**: [Model Context Protocol](https://modelcontextprotocol.io)
- **Railway Documentation**: [docs.railway.app](https://docs.railway.app)
- **Original Repository**: [datacommonsorg/agent-toolkit](https://github.com/datacommonsorg/agent-toolkit)

## Support

For issues related to:
- **This deployment**: Open an issue on this repository
- **Data Commons API**: Visit [datacommons.org/support](https://datacommons.org/support)
- **Railway platform**: Check [Railway documentation](https://docs.railway.app)

---

**Built with ❤️ for the MCP ecosystem**