Socrata MCP Server

An MCP server that gives Claude tools to explore and query any 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:

python3 --version

If you need to install or upgrade Python:

macOS: brew install python (requires Homebrew)
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 and check Add to PATH during install

1. Clone or copy this folder

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

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

pip install -r requirements.txt

5. Verify the install

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)

{
  "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)

{
  "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:

{
  "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.

This code was generated using Claude 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"

socrata-mcp