io.github.cyanheads/college-scorecard-mcp-server

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

Search, compare, and analyze U.S. college data — costs, earnings, programs, and outcomes.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "college-scorecard-mcp-server": {
      "url": "https://college-scorecard.caseyjhand.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (9)

• scorecard_lookup_cip read-only

  Search the Classification of Instructional Programs (CIP) taxonomy by keyword or partial name. Returns matching CIP codes with standard titles. Use this before passing cip_code filters to scorecard_search_programs or scorecard_get_programs when you know a program by name but not its code. Served entirely from embedded static data — no API call, no rate limit impact.

  Parameters:

  • query (required) — string — Search term — program name keyword (e.g. "computer science", "nursing", "business"). Matches against CIP titles and family names.
  • limit — integer — Requested limit; serving cap 50, hard ceiling 1,000.

  Hints: read-only yes · destructive not declared · idempotent yes · open-world no

• scorecard_list_fields read-only

  Search the College Scorecard field catalog by keyword. Returns matching field paths, descriptions, data types, and whether each field supports API-side sorting. Use before passing custom field paths to the fields parameter on scorecard_get_school to find a supported path. Served entirely from embedded static data — no API call, no rate limit impact.

  Parameters:

  • query (required) — string — Keyword to search the field catalog (e.g. "tuition", "earnings", "admissions", "debt"). Matches against field paths, descriptions, and category names.
  • limit — integer — Requested limit; serving cap 100, hard ceiling 1,000.

  Hints: read-only yes · destructive not declared · idempotent yes · open-world no

• scorecard_search_schools read-only

  Search and filter U.S. colleges and universities by name, location, type, size, and acceptance rate. Returns core identity and cost metrics. Use scorecard_get_school for profiles or scorecard_search_programs for program rankings. Geographic distance requires a U.S. ZIP; ZIP alone uses the provider default radius. State accepts comma-separated two-letter codes (e.g. WA,CA). Ownership: 1=public, 2=private nonprofit, 3=for-profit. Degree level: 0=non-degree, 1=certificate, 2=associate, 3=bachelor, 4=graduate.

  Parameters:

  • zip — string — Five-digit U.S. ZIP or ZIP+4. Alone uses the provider default radius; blank is unset.
  • page — integer — Zero-indexed page number for pagination.
  • sort — string — Upstream sort expression on an indexed field, e.g. "latest.cost.avg_net_price.overall:asc" or ":desc" for reverse order. Use scorecard_list_fields for sort support; omission keeps API ordering.
  • query — string — School name search — partial or full name; all words must appear.
  • state — string — Comma-separated two-letter state codes; case and whitespace normalized, blanks unset.
  • cip_code — string — Filter to schools offering this CIP 4-digit program code (e.g. "11.07"). Use scorecard_lookup_cip to find codes.
  • distance — string — Nonnegative radius: bare miles, mi, or km, including decimals. Requires meaningful zip.
  • men_only — boolean — True selects men-only institutions; false selects institutions explicitly marked not men-only. Omit to include unknown values.
  • per_page — integer — Results per page (max 100).
  • ownership — integer — Control type: 1=public, 2=private nonprofit, 3=private for-profit.
  • size_range — object — Undergraduate enrollment size range. Omit for no size filter.
  • women_only — boolean — True selects women-only institutions; false selects institutions explicitly marked not women-only. Omit to include unknown values.
  • degree_level — integer — Predominant degree: 0=non-degree/certificate, 1=certificate, 2=associate, 3=bachelor, 4=graduate.
  • acceptance_rate_range — object — Acceptance rate range as decimals (0–1). Omit for no filter.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• scorecard_get_school read-only

  Institutional profiles for one or more school IDs. Accepts up to 1,000 elements, deduplicates normalized IDs, serves the first 100 distinct IDs, and reports missing and unprocessed IDs separately. Use scorecard_compare_schools for comparisons. Custom fields return requested paths and their JSON values in selected_fields, absent paths in absent_fields, and real identity; default profiles include costs, admissions, outcomes, aid, and completion rates.

  Parameters:

  • id (required) — Positive safe integer school ID or up to 1,000 raw elements. First 100 distinct normalized IDs served; discover IDs with scorecard_search_schools.
  • fields — string — Optional comma-separated list of custom field paths from scorecard_list_fields. Overrides the default field set.

  Hints: read-only yes · destructive not declared · idempotent yes · open-world yes

• scorecard_get_programs read-only

  All field-of-study programs at one school with median earnings 1 year after the highest credential, cumulative Stafford/Grad PLUS debt, and IPEDS awards for each year of the pooled debt cohort. Institution-level 6/8/10-year earnings are available via scorecard_get_earnings. Null or absent earnings have unknown cause; suppressed=true requires an explicit provider privacy marker. Use scorecard_lookup_cip to find CIP codes by name.

  Parameters:

  • id (required) — School ID from scorecard_search_schools.
  • cip_code — string — Filter to one 4-digit CIP code, dotted or undotted (e.g. "11.07" or "1107" for Computer Science). Returns one row per credential level the school offers in that program.
  • min_earnings — number — Minimum 1-year post-graduation median earnings filter.
  • credential_level — integer — Filter by credential level: 1=undergraduate certificate, 2=associate, 3=bachelor, 4=post-baccalaureate certificate, 5=master, 6=doctoral, 7=first professional, 8=graduate/professional certificate, 99=non-credential.

  Hints: read-only yes · destructive not declared · idempotent yes · open-world yes

• scorecard_get_earnings read-only

  Institution-level earnings of federally aided undergraduate entrants working and not enrolled, regardless of completion. Reports medians at 6/8/10 years after entry, 6/10-year percentiles, and non-male/male 6-year medians. For graduate program earnings use scorecard_get_programs. years selects API data-file start years (1996–2025), including files without earnings observations. Per-metric availability and official cohort/measurement/dollar context accompany values; unknown metadata stays absent. No re-inflation is performed.

  Parameters:

  • id (required) — School ID from scorecard_search_schools.
  • years — array — Optional API data-file start years from 1996–2025 (e.g. [2003, 2011, 2020]); valid files may lack observations. Omit or pass [] for snapshot only.

  Hints: read-only yes · destructive not declared · idempotent yes · open-world yes

• scorecard_search_programs read-only

  Find programs by CIP code across institutions, ranked by median earnings within the fetched school page. Accepts school-side filters (state, ownership, max cost). Minimum earnings is applied locally; totals and pagination count schools before local program filtering. Use scorecard_lookup_cip to convert program names to CIP codes. Returns school names and IDs alongside program earnings, cumulative Stafford/Grad PLUS debt, and IPEDS awards for follow-up calls to scorecard_get_school or scorecard_get_programs.

  Parameters:

  • page — integer — Zero-indexed page number.
  • state — string — Comma-separated two-letter state codes; case and whitespace normalized, blanks unset.
  • cip_code — string — CIP 4-digit code to search for (e.g. "11.07" for Computer Science). Use scorecard_lookup_cip to find codes.
  • max_debt — number — Maximum median cumulative Stafford/Grad PLUS debt across institutions at the same academic level, inclusive; excludes unavailable debt.
  • per_page — integer — Schools per page (max 100); program rows may exceed this count.
  • ownership — integer — Restrict to school type: 1=public, 2=private nonprofit, 3=for-profit.
  • min_earnings — number — Minimum 1-year median earnings, inclusive. Filters this school page locally and excludes unavailable earnings; school totals are unchanged.
  • program_name — string — Case-insensitive title substring matched within the fetched school page. Ignored when cip_code is provided; use cip_code for upstream program matching.
  • max_net_price — number — Maximum average net price at the school.
  • credential_level — integer — Provider credential selector: 1=undergraduate certificate, 2=associate, 3=bachelor, 4=post-baccalaureate certificate, 5=master, 6=doctoral, 7=first professional, 8=graduate/professional certificate, 99=non-credential; other integer levels may return no matches.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• scorecard_compare_schools read-only

  Side-by-side comparison of 2–5 schools with ordinal competition ranks within the selected set (ties share a rank). Topics: costs (tuition, net price by income bracket, debt), admissions (acceptance rate, SAT/ACT, enrollment), outcomes (completion, earnings, repayment), aid (Pell grants, federal loans, debt, repayment). Use scorecard_get_school for full profiles.

  Parameters:

  • ids (required) — array — Array of 2–5 school unit IDs to compare.
  • topic (required) — string — Comparison topic: costs, admissions, outcomes, or aid.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

• scorecard_value_analysis read-only

  Analyze costs, debt, repayment progress, and earnings for one school. Returns debt-to-earnings and net-price-to-annual-earnings ratios alongside the source figures. family_income selects the applicable net-price bracket. Repayment progress is the share of borrowers paying down principal 3 years after entering repayment.

  Parameters:

  • id (required) — School ID from scorecard_search_schools.
  • family_income — number — Annual family income in dollars. When provided, net price is shown for the applicable income bracket.

  Hints: read-only yes · destructive not declared · idempotent not declared · open-world yes

Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.