College Scorecard MCP Server

Tools

9 tools for working with U.S. Department of Education College Scorecard data — institution search, program-level earnings, cost and outcomes analysis, and structured comparison:

scorecard_search_schools

Search for institutions using name, location, and institutional filters.

• Free-text name search plus typed filters: state, ownership (public/private nonprofit/private for-profit), degree level, size range, acceptance rate range

• Geographic proximity filtering by U.S. zip code and distance (miles or km)

• CIP code filter to find schools offering a specific program family

• Pagination (per_page up to 100, zero-indexed page)

• Returns core identity and cost metrics for quick scanning

scorecard_get_school

Fetch a full institutional profile by school ID.

• Accepts a single ID or an array of IDs (batch fetch up to 100 per page)

• Covers costs, admissions, outcomes, financial aid, demographics, and completion rates

• Optional fields override for callers who need a narrower or broader field set

• For side-by-side comparison on a specific dimension, use scorecard_compare_schools

scorecard_compare_schools

Normalized comparison across 2–5 institutions on a named topic.

• Four topics: costs, admissions, outcomes, aid — each pulls a curated topic-specific field set

• Computes within-set percentile ranks and relative deltas — structured output an agent cannot reconstruct from raw profiles

• Single API call for all schools; normalization applied post-fetch

• Distinct from scorecard_get_school multi-ID: output shape is rows, not profiles

scorecard_get_programs

List all field-of-study programs at one school with earnings and debt data.

• Returns P25/median/P75 earnings 1 year after graduation, median debt at graduation, and enrollment figures per program

• Filter by CIP code to return only matching programs

• Filter by credential_level (certificate, associate's, bachelor's) and minimum earnings threshold

• Primary source for program-level earnings — institution-level earnings at 6/8/10 years are available via scorecard_get_earnings

• FERPA suppression surfaced as structured suppressed: true flag with suppression_note, not bare null

scorecard_search_programs

Find programs by CIP code or name across all institutions, ranked by median earnings.

• Program-centric: "which schools in Washington have CS programs with median earnings over $80k?"

• Accepts school-side filters: state, ownership, max net price

• Earnings and debt thresholds for filtering results

• Returns school name, school ID, and unit ID alongside program metrics for follow-up chaining

• Sorting applied post-fetch where earnings fields are not API-indexed

scorecard_get_earnings

Institution-level post-graduation earnings for one school.

• Median and P25/P75 earnings at 6, 8, and 10 years after entry

• Optional gender breakdown when available

• years parameter for time-series analysis; defaults to latest.* for current-state queries

• Reflects outcomes across all graduates, not broken down by program

scorecard_value_analysis

Workflow tool: "Is this school worth it?"

• Parallel-fetches cost/debt/repayment and earnings data in two concurrent requests

• Computes ROI metrics the API does not pre-calculate: debt-to-earnings ratio (median debt / 6-year earnings), net price to first-year earnings ratio, and 3-year loan repayment rate

• family_income parameter selects the applicable net price bracket

• Fetches peer school identifiers (same Carnegie category and ownership) for comparative median values

• Returns all source figures alongside derived metrics — callers can audit the arithmetic

• data_notes flags any suppressed or null fields with structured explanations

scorecard_lookup_cip

Search CIP codes by keyword or partial name.

• Covers the full ~2,400-code CIP taxonomy embedded as static data

• No API call required — zero rate-limit impact, works offline

• Required before using CIP-based filters when the caller knows a program by name but not code

• Returns matching codes with standard titles

scorecard_list_fields

Search the Scorecard field catalog by keyword.

• ~2,800 field entries from the data dictionary, embedded as static data

• Returns field paths, descriptions, data types, and whether the field supports API-side sorting

• No API call required — zero rate-limit impact

• Use before passing custom fields parameters to search/get tools

Related MCP server: mcp-college-scorecard

Resources and prompts

All resource data is also reachable via tools. Use scorecard_search_schools or scorecard_get_school to discover school IDs before constructing resource URIs.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats

• Pluggable auth: none, jwt, oauth

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports

College Scorecard-specific:

• Full College Scorecard API coverage: ~6,500 Title IV institutions, ~2,800 data fields spanning costs, outcomes, demographics, financial aid, and field-of-study earnings

• Program-level post-graduation earnings: actual median earnings 1 year after graduation for ~6,500 school × CIP code combinations

• Field pre-selection per tool — curated ~10–20 field sets appropriate to each tool's purpose; optional fields override for custom queries

• Embedded CIP code taxonomy and field catalog: both served as static data with zero API calls and zero rate-limit impact

• Geographic filtering via U.S. zip code + distance radius

• scorecard_value_analysis workflow tool computes ROI metrics (debt-to-earnings ratio, net price to first-year earnings) that require multiple API round-trips and post-processing arithmetic

Agent-friendly output:

• FERPA suppression surfaced as structured suppressed: true flag with suppression_note — prevents hallucination of missing earnings data at selective schools with small cohorts

• Derived metrics alongside source figures in scorecard_value_analysis — agents can verify arithmetic and branch on computed values, not raw numbers

• Percentile ranks and relative deltas in scorecard_compare_schools — structured output an agent cannot reconstruct from raw profiles without knowing the full comparison set

• Post-fetch sorting documented and handled transparently — callers never hit API errors on non-indexed sort fields

Getting started

Add the following to your MCP client configuration file. See api.data.gov/signup for a free API key.

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/college-scorecard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SCORECARD_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/college-scorecard-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SCORECARD_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SCORECARD_API_KEY=your-api-key",
        "ghcr.io/cyanheads/college-scorecard-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 SCORECARD_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).

• A College Scorecard API key — free registration at api.data.gov/signup. Rate limit: 1,000 requests/hour per key.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/college-scorecard-mcp-server.git

2. Navigate into the directory:

cd college-scorecard-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set SCORECARD_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t college-scorecard-mcp-server .
docker run --rm -e SCORECARD_API_KEY=your-key -p 3010:3010 college-scorecard-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/college-scorecard-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.