# Socrata MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Generated with Claude](https://img.shields.io/badge/Generated%20with-Claude%20by%20Anthropic-blue)](https://www.anthropic.com)

An MCP server that gives Claude tools to explore and query any [Socrata](https://www.tylertech.com/products/socrata) open data portal.

## Tools

| Tool | Description |
|------|-------------|
| `search_datasets` | Search for datasets by keyword, optionally scoped to a specific portal domain |
| `get_dataset_metadata` | Get column definitions and metadata for a dataset |
| `query_dataset` | Query rows using SoQL WHERE / SELECT / ORDER |
| `aggregate_dataset` | GROUP BY aggregation with count/sum/avg etc. |
| `list_portal_categories` | List dataset categories on a specific portal |

---

## Installation

### Prerequisites

You need **Python 3.10 or newer**. Check your version:

```bash
python3 --version
```

If you need to install or upgrade Python:

- **macOS**: `brew install python` (requires [Homebrew](https://brew.sh))
- **Ubuntu/Debian / WSL**: `sudo apt update && sudo apt install -y python3 python3-venv python3-pip`
- **Fedora/RHEL**: `sudo dnf install python3`
- **Windows 11 native**: Download from [python.org](https://www.python.org/downloads/) and check *Add to PATH* during install

---

### 1. Clone or copy this folder

```bash
git clone https://github.com/your-username/socrata-mcp.git
cd socrata-mcp
```

Or just copy the `server.py` and `requirements.txt` files into a folder of your choice.

---

### 2. Create a virtual environment

```bash
python3 -m venv .venv
```

---

### 3. Activate the virtual environment

| Platform | Command |
|----------|---------|
| **macOS / Linux / WSL** | `source .venv/bin/activate` |
| **Windows (cmd.exe)** | `.venv\Scripts\activate.bat` |
| **Windows (PowerShell)** | `.venv\Scripts\Activate.ps1` |

Your prompt will change to show `(.venv)` when it is active.

---

### 4. Install dependencies

```bash
pip install -r requirements.txt
```

---

### 5. Verify the install

```bash
python3 server.py --help
```

You should see an error like:
```
RuntimeError: SOCRATA_DOMAIN environment variable is required
```
That means the server loaded correctly — it just needs your credentials configured (see below).

---

## Configuration

Both environment variables are **required**. The server will not start without them.

| Variable | Description | Example |
|----------|-------------|---------|
| `SOCRATA_DOMAIN` | Hostname of the Socrata portal | `data.delaware.gov` |
| `SOCRATA_APP_TOKEN` | API token from your Socrata account | `abc123xyz...` |

To get an API token: log in to your Socrata portal → Developer Settings → Create New App Token.

---

## Add to Claude Desktop

Claude Desktop reads its MCP server list from a JSON config file. Edit the file for your platform:

| Platform | Config file location |
|----------|----------------------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows 11** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **WSL** | Use the **Windows** path above — Claude Desktop runs on Windows, not inside WSL |

### macOS / Linux (native)

```json
{
  "mcpServers": {
    "socrata": {
      "command": "/absolute/path/to/socrata-mcp/.venv/bin/python3",
      "args": ["/absolute/path/to/socrata-mcp/server.py"],
      "env": {
        "SOCRATA_DOMAIN": "data.delaware.gov",
        "SOCRATA_APP_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

Replace `/absolute/path/to/socrata-mcp` with the real path. Find it by running `pwd` inside the project folder.

### Windows 11 (native Python)

```json
{
  "mcpServers": {
    "socrata": {
      "command": "C:\\Users\\YourName\\socrata-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourName\\socrata-mcp\\server.py"],
      "env": {
        "SOCRATA_DOMAIN": "data.delaware.gov",
        "SOCRATA_APP_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

### Windows 11 with WSL

Claude Desktop runs on Windows but can launch a WSL process via `wsl.exe`:

```json
{
  "mcpServers": {
    "socrata": {
      "command": "wsl.exe",
      "args": [
        "--exec",
        "/home/your-wsl-username/socrata-mcp/.venv/bin/python3",
        "/home/your-wsl-username/socrata-mcp/server.py"
      ],
      "env": {
        "SOCRATA_DOMAIN": "data.delaware.gov",
        "SOCRATA_APP_TOKEN": "your-api-key-here"
      }
    }
  }
}
```

Replace `your-wsl-username` with your WSL username (run `whoami` inside WSL to check).

---

After editing the config, **restart Claude Desktop** and you should see the Socrata tools available.

---

## License

This project is licensed under the [MIT License](LICENSE).

This code was generated using [Claude](https://www.anthropic.com) by Anthropic.

---

## Example queries

- "What datasets are available on the Delaware open data portal?"
- "Show me the top vendors by contract spend in FY2025"
- "What columns are in dataset sifm-293u?"
- "Which agencies spent the most on cloud solutions last year?"
- "Search for education datasets on data.delaware.gov"