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"