urban-edc-mcp

An MCP server that routes K-12 education data requests to whichever public upstream source actually has the answer:

• Urban Institute Education Data Portal — broad, harmonized national K-12 indicators (directory, enrollment, and more)
• EDC / Zelma — 50-state assessment results
• NAEP ("The Nation's Report Card") — state- and national-level reading/math/science scores, comparable across states
• MA Education to Career (E2C) Hub — Massachusetts MCAS results and other MA-specific datasets

All four sources are free, public APIs — no API key is required for normal use (MA E2C supports an optional app token to raise anonymous rate limits; see below).

This server is intentionally federated, not a warehouse. It does not mirror or cache upstream datasets. On every call it:

1. inspects the request,
2. decides which upstream source is the better fit (or uses the metric_name you gave it),
3. calls that source directly,
4. returns data plus provenance and comparability notes.

Why federate instead of picking one source?

Each source has a different scope and a different comparability guarantee, and mixing them up produces wrong analysis:

• EDC state assessment results are not comparable across states (different tests, scales, and cut scores).
• NAEP is comparable across states — use it for cross-state comparisons.
• MCAS (MA E2C) is on its own 440–560 scale, distinct from both EDC's state scales and NAEP's 0–500 scale.
• Urban is the right default for broad national indicators (directory, enrollment) that aren't assessment scores at all.

The router encodes these rules so an LLM calling this server doesn't have to know them, and every response carries the comparability caveat that applies to it.

Install this with an AI assistant (no terminal needed)

If you use a coding assistant that can read files and run commands on your own computer — Claude Code, Codex CLI, Cursor, or similar — you don't need to install anything yourself. Open a chat with that tool and paste the block below as-is. It runs entirely from this GitHub repo; nothing needs to be published anywhere first, and no API key or account is required.

This only works with a tool that has file and terminal access on your machine. It will not work if you paste it into the plain Claude.ai or ChatGPT website chat — those can't edit files or run commands on your computer.

Please install the MCP server from https://github.com/sribnick-coder/urban-edc-mcp so I can
use it here. Steps:

1. Check whether the `uv` tool is installed (`uv --version`). If it isn't, install it — see
   https://docs.astral.sh/uv/getting-started/installation/ for the right one-line installer
   for my operating system.
2. Add an MCP server entry named "urban-edc" to whichever MCP config file you use, with:
   - command: uvx
   - args: ["--from", "git+https://github.com/sribnick-coder/urban-edc-mcp", "urban-edc-mcp"]
3. Restart or reload yourself so the new server is picked up.
4. Confirm it worked by asking me: "What were the NAEP grade 4 reading scores in 2024 for
   California, Texas, and New York?" and showing me the result.

No API keys, accounts, or local installs are needed for this — it runs straight from GitHub
via `uvx`.

That's it — the assistant does the rest, and you can ask it in plain English about K-12 data (assessment scores, enrollment, etc.) once it confirms the tool is loaded.

Install manually

Requires Python 3.11+.

Run without installing, straight from GitHub (recommended, via uv)

uvx --from git+https://github.com/sribnick-coder/urban-edc-mcp urban-edc-mcp

This is not yet published to PyPI, so the --from git+... form above is required for now. If it's published there later, plain uvx urban-edc-mcp will also work.

From source

git clone https://github.com/sribnick-coder/urban-edc-mcp.git
cd urban-edc-mcp
uv venv
source .venv/bin/activate  # .venv\Scripts\activate on Windows
uv sync

Or with pip:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configure in an MCP client

Add this to your client's MCP config (e.g. Claude Desktop's claude_desktop_config.json, or a project's .mcp.json for Claude Code):

Via uvx, straight from GitHub (no local install needed):

{
  "mcpServers": {
    "urban-edc": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sribnick-coder/urban-edc-mcp", "urban-edc-mcp"]
    }
  }
}

From a local install (console script installed by pip install -e . / uv sync):

{
  "mcpServers": {
    "urban-edc": {
      "command": "urban-edc-mcp"
    }
  }
}

Optional — raise MA E2C rate limits. Set E2C_APP_TOKEN in your environment (or the config's env block) to a free Socrata application token if you'll be making many MA E2C / MCAS calls. Not required for normal use.

Run locally for development

# MCP Inspector (interactive dev UI)
uv run mcp dev src/urban_edc_mcp/server.py

# Direct stdio server
uv run python -m urban_edc_mcp.server

Tools exposed

• find_data — given a natural-language question, recommends which source to use (Urban / EDC / NAEP / MA E2C), with a confidence level, comparability notes, and a ready-to-use get_data call.
• get_data — fetches data from the selected source. Cleanest when you pass a supported metric_name; falls back to raw source-specific parameters for anything not yet catalogued.
• explain_metric — describes supported metrics, metric families, and sources. Call with no arguments to list everything available.
• get_lineage — returns full provenance (upstream endpoint, request params, route reason, source docs) for any prior get_data result, keyed by its request_id.

Supported metric_name values

metric_name	Source	Notes
naep_scores	NAEP	Comparable across states. Requires subject, grade.
ma_mcas_results	MA E2C	Massachusetts MCAS. Not comparable to other states.
ma_e2c_dataset	MA E2C	Any dataset on the E2C portal. Requires ma_dataset_id.
state_assessment	EDC	50-state assessment data. Not comparable across states.
school_directory	Urban	Requires year.
school_enrollment_by_grade	Urban	Requires year, grade.

For anything else on Urban, pass urban_path directly (e.g. "schools/ccd/directory/2013/"), or raw EDC/Socrata filters via edc_filters / ma_where. See the docstring on get_data (src/urban_edc_mcp/server.py) for the full parameter reference and worked examples per source, and use explain_metric at runtime to inspect any metric before calling it.

Example prompts

• "Compare grade 4 reading NAEP scores across California, Texas, and New York for 2024."
• "Find Rhode Island's grade 4 math assessment results for 2024."
• "Get Boston's district-level MCAS ELA results for 2024."
• "List all schools in the Urban school directory for 2013."

Scope and limitations

This is a deliberately small gateway, not a full data warehouse. It does not solve:

• cross-source joins,
• full entity resolution (e.g. matching district names across sources),
• full Urban endpoint discovery beyond the metrics catalogued above,
• long-term caching.

Development

uv sync --all-extras
uv run pytest                      # full suite
uv run pytest -m "not network"     # skip tests that hit real upstream APIs
bash predeploy.sh --offline        # pre-deploy checklist without network calls

TESTING.md documents the test layout and coverage in more detail.

License

MIT — see LICENSE.