Compare-Zipcodes MCP Server

A FastMCP-compatible Model Context Protocol (MCP) server for comparing zipcode-level demographic distributions. It includes a tool for detecting statistically significant differences in population segments—based on age, gender, and ethnicity—between two ZIP Code Tabulation Areas (ZCTAs), using z-score analysis over synthetic census data.

This repository also includes instructions on how to integrate the MCP server with Claude Desktop.

Features

• Compares zip code demographics based on age x gender x ethnicity using Z-score based anomaly detection
• Synthetic population and household census data integration via .pkl files generated from AgentTorch

Installation

git clone https://github.com/anna8murphy/mcp-compare-zipcodes.git
cd mcp-compare-zipcodes

# install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# set up environment
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx

Start the server

Run the server:

uv run compare-zipcodes.py

Running the server will make the compare_regions tool available, which returns a summary of statistically significant demographic differences (z-score > 2) between two ZIP codes based on age, gender, and ethnicity groupings.

Usage on Claude Desktop

Open the Claude for Desktop App configuration in a text editor:

~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the server:

{
    "mcpServers": {
        "mcp-compare-zipcodes": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-compare-zipcodes",
                "run",
                "compare-zipcodes.py"
            ]
        }
    }
}

Example Prompt: Compare the demographic statistics of the following zipcodes: 02139 and 10036.

Project Structure

mcp-compare-zipcodes/
├── README.md              # documentation
├── compare-zipcodes.py    # main script for Claude integration
├── server.py              # MCP server implementation
├── pyproject.toml         # Python project configuration
└── uv.lock                # uv package manager lock file