College Scorecard MCP Server
Public Hosted Server: https://college-scorecard.caseyjhand.com/mcp
Overview
US college data from the Department of Education College Scorecard: costs, earnings, programs, and outcomes across roughly 6,500 institutions. Search and compare schools, look up earnings by field of study, and compute ROI metrics like debt-to-earnings ratio.
Tools
Tool | Description |
| Search institutions by location, price, completion, operating certification, and other school characteristics. Sort by fields with API sort support. |
| Institutional profiles with costs, admissions, aid, demographics, completion, and borrower repayment outcomes. |
| Side-by-side comparison of up to five schools. Includes ranks and leaders for eligible metrics. |
| Paged field-of-study outcomes: completion-based 1/4-year earnings, legacy highest-credential earnings, debt, and campus awards with separate provenance. |
| Find programs by CIP and credential or keyword, retain degree identity, and rank earnings within each fetched school page. |
| Earnings of federally aided undergraduate entrants working and not enrolled, regardless of completion: 6/8/10-year medians, 6/10-year P25/P75, and non-male/male 6-year medians. |
| Combines cost, debt, repayment, and earnings data with debt-to-earnings and net-price-to-earnings ratios. |
| Search all 464 current NCES CIP 2020 four-digit groups by code, keyword, or related program name. Served offline. |
| Search the Scorecard field catalog by keyword. Returns matching field paths, descriptions, data types, and sort support. Use before passing custom |
Resources
Resource | Description |
| Institutional profile by unit ID — injectable context for school-specific conversations |
| First page of program-level outcomes for a school |
| Continuation through a school's programs in provider order |
All resource data is also reachable via tools. Use scorecard_search_schools or scorecard_get_school to discover school IDs before constructing resource URIs.
The college-scorecard-guide covers campus/CIP identity, paging, outcome populations, OPEID6 pooling, and price-basis gates. It ships with plugins, npm, Docker, and MCPB, and is served through the MCP Skills extension.
Prompts
Prompt | Description |
| Structures a multi-school comparison analysis using Scorecard data |
Related MCP server: mcp-college-scorecard
Capability reference
scorecard_search_schools tool
Search by name, state, ownership, degree level, size, acceptance rate, CIP code, or ZIP and distance (miles or
km). State lists acceptWA,CA.Apply
max_net_price(inclusive dollars),min_completion_rate(inclusive 0–1), andlocale(city,suburb,town, orrural) before paging. These filters require reported values. Negative price ceilings normalize to $0 with a notice.operating,hbcu,men_only, andwomen_onlymatch explicit true or false values. Omit a flag to include unknown values.operating: falsemeans the school lacks current operating certification. Verify actual closure separately.Use
scorecard_list_fieldsto choose a supported sort such aslatest.cost.avg_net_price.overall:asc. Omit sort to preserve API order.pagestarts at zero andper_pageis capped at 100.
scorecard_get_school tool
Accepts a school ID or an array of up to 1,000. The first 100 distinct IDs are fetched;
missing_idslists fetched IDs with no record andunprocessed_idslists the excess.Default profiles cover costs, admissions, outcomes, financial aid, demographics, and completion rates. Custom
fieldsreturnsselected_fieldswith the requested values, andabsent_fieldslists requested paths missing from the response.Projected program arrays use
program_limit(default 20, capped at 100) andprogram_offset; follow each school'sprogram_pagescontinuation. Raw values and provider positions stay aligned.Profiles include operating certification, HBCU, and single-sex flags as booleans when known, omitting unknown flags. The discontinued three-year declining-balance rate carries its 2016–17 file, repayment-entry cohorts, and measurement period.
borrower_repaymentreports making progress, default, and paid in full at two and four years for OPEID6-pooled undergraduate federal Direct Loan borrowers. Each horizon has its own provenance and cohort count when available. Published bins are preserved verbatim, and only decimal point estimates have numeric values.
scorecard_compare_schools tool
Accepts 2–1,000 raw unit IDs and compares the first five distinct normalized IDs on
costs,admissions,outcomes, oraid.missing_idswere queried;unprocessed_idswere not.Equal eligible values share a rank (1, 1, 3). Admissions metrics, aid participation rates, shared OPEID6 outcome rows, and mixed academic/program-year price rows are unranked. A single found school yields values without ranks or leaders.
Each cell's
availabilitydistinguishes available, unavailable, and privacy-suppressed values. Repayment rows rank the historical three-year declining-balance measure and identify its vintage.
scorecard_get_programs tool
Accepts one school ID, with optional CIP code (dotted or undotted),
credential_level, and minimum earnings filters. A school with no matching programs returns an empty collection; a nonexistent school is a lookup error.Text results lead with completion-based one- and four-year medians, counts, and availability. Legacy
earnings_1yr_medianandearnings_countappear separately with their highest-credential provenance.min_earningsand ordering use completion-based one-year earnings, with no legacy fallback. Page withlimit(default 20, capped at 100) andoffset;totalcounts matches before paging, andnextOffsetis null at the end.median_debtis completers' cumulative Stafford/Grad PLUS borrowing.ipeds_awards_year1andipeds_awards_year2count awards in each year of the pooled debt cohort, not students.
scorecard_search_programs tool
Search by CIP code or program name, with optional integer
credential_level(1–8 and 99), state, ownership, net price, earnings, and debt filters.page/per_pagepaginate schools;offset/limitpage matching program rows within that school page.Returns school IDs and names with program metrics,
credential_level, andcredential_title. Available earnings sort first; availability, debt, and award fields matchscorecard_get_programs.min_earningsfilters locally, so totals and pagination are upstream school counts before filtering. Earnings and debt thresholds are inclusive and exclude unknown values. Negativemax_net_priceandmax_debtnormalize to $0 with a notice.Follow
nextuntil null: it drains program rows on the current school page before advancing.showncounts returned programs;schools_showncounts fetched schools. Rankings use current completion-based one-year earnings within the fetched page only.
scorecard_get_earnings tool
Accepts one school ID and optional data-file start
yearsfrom 1996–2025 (file vintages, not entry years). Duplicate years collapse in caller order. Omityearsor pass[]for the snapshot only.Covers federally aided undergraduate entrants working and not enrolled, regardless of completion: medians at 6/8/10 years after entry, 6/10-year P25/P75, and non-male/male 6-year medians.
current_availabilityandtrend[].availabilityclassify each metric.current_contextandtrend[].contextgivedata_file_year,entry_cohorts,measurement_years, anddollar_year; values keep the provider's dollar basis, so check it before comparing across vintages.
scorecard_value_analysis tool
Accepts one school ID. Optional
family_incomeselects the applicable net price bracket ($0–30k, $30k–48k, $48k–75k, $75k–110k, or $110k+). Negative income normalizes to $0 with a notice.Returns ratios alongside their source figures.
effective_net_priceis the price used, andnet_price_basisisincome_bracket,overall, orunavailable.If the bracket is missing, the overall price is used and
data_notessays so. Ratios require positive annual earnings.Tuition and attendance independently prefer academic-year prices, otherwise reported program-year prices; each has its own basis. Program tuition never substitutes for net price. OPEID6-pooled outcomes are identified alongside campus prices.
Returns the same two- and four-year borrower statuses and historical three-year declining-balance context as the default school profile.
scorecard_lookup_cip tool
Search by nonblank keyword or partial name (default limit 20, capped at 50). Dotted
11.07and undotted1107are equivalent; continue withoffsetand returnednextOffsetwhile more results remain.Returns exact group titles and family identities from all 464 current NCES CIP 2020 four-digit groups. Six-digit queries such as
11.0701and110701resolve to their four-digit group with a notice. Program tools take the four-digit group. No matches return an empty collection with guidance.
scorecard_list_fields tool
Search 94 curated offline field entries by nonblank query (default limit 30, capped at 100). Use before passing custom
fieldstoscorecard_get_school, including pooled full-time retention for four-year and less-than-four-year institutions.Returns field paths, descriptions, data types, categories, and observed API sorting support.
tipflags results containing unsortable fields.
scorecard://school/{id} resource
Institutional profile as
application/json— identity, cost, admissions, outcomes, aid, and completion dataidis the school unit ID (integer as string) fromscorecard_search_schoolslistreturns a handful of example school URIs; usescorecard_search_schoolsto discover others
scorecard://programs/{id} resource
First 20 program rows as
application/json, in provider order, with current/legacy earnings populations, scope, provenance, debt, and campus awards. Legacy nullable metrics retain null; new metrics expose availability.idis the school unit ID fromscorecard_search_schoolslistreturns a handful of example school URIs; usescorecard_search_schoolsto discover othersFollow
nextUrithroughscorecard://programs/{id}/page/{offset}/{limit}until null. Page limits above 100 normalize to 100, with a hard ceiling of 1,000; offsets are zero-based. Tool ordering differs, so do not reuse offsets between tools and resources.
scorecard_compare_prompt prompt
Arguments:
school_names(comma-separated list) andfocus(costs|outcomes|programs), both requiredcostsandoutcomesrun school discovery,scorecard_compare_schools, profiles, and value analysis.programsruns school discovery, CIP lookup, andscorecard_get_programsper school, then compares completion earnings, debt, and IPEDS awards for matching credentials.
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
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 completion earnings at one and four years, alongside legacy highest-credential outcomes; each series carries its population and vintage
Field pre-selection per tool — curated field sets appropriate to each tool's purpose; optional
fieldsoverride for custom queriesEmbedded CIP taxonomy (464 groups) and field catalog (94 fields) served offline
Geographic filtering via U.S. zip code + distance radius
Agent-friendly output:
Availability distinguishes numbers (including zero), missing values, and explicit
PS/PrivacySuppressedprovider markersDerived metrics sit alongside source figures in
scorecard_value_analysis, andscorecard_compare_schoolsadds ordinal ranksSchool sorting uses fields with observed API sort support. Six-year earnings and pooled full-time retention can be projected but cannot be used as sort fields.
Provider failures report distinct validation, authentication, throttling, timeout, and availability reasons; availability uses
api_errorand cancellation remainsRequestCancelled
Getting started
Public Hosted Instance
A public instance is available at https://college-scorecard.caseyjhand.com/mcp — no installation required. No API key needed; the instance supplies its own. Point any MCP client at it via Streamable HTTP:
{
"mcpServers": {
"college-scorecard-mcp-server": {
"type": "streamable-http",
"url": "https://college-scorecard.caseyjhand.com/mcp"
}
}
}Self-Hosted / Local
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/mcpPrerequisites
Bun v1.4.4 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
Clone the repository:
git clone https://github.com/cyanheads/college-scorecard-mcp-server.gitNavigate into the directory:
cd college-scorecard-mcp-serverInstall dependencies:
bun installConfigure environment:
cp .env.example .env
# edit .env and set SCORECARD_API_KEYConfiguration
All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:
Variable | Description | Default |
| Required. API key from api.data.gov (1,000 req/hour). | — |
| Transport: |
|
| HTTP server port |
|
| HTTP endpoint path where the MCP server is mounted |
|
| Public HTTP or HTTPS base URL for TLS-terminating reverse-proxy deployments. Omit credentials, query parameters, and fragments. | none |
| HTTP session mode: |
|
| Authentication: |
|
| Required | none |
| Required | none |
| Log level ( |
|
| Opt-in forced-GC loop interval in ms (Bun only); try |
|
| Directory for log files. Relative paths resolve from the server package root. |
|
| Storage backend: |
|
|
|
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:httpRun 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-serverThe 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
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| Resource definitions. School profile and program outcomes resources. |
| Published usage gates for school/program comparisons and complete retrieval. |
| Prompt definitions. Multi-school comparison prompt. |
|
|
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageRegister new tools, resources, and prompts in the
createApp()arrays insrc/index.tsWrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
During maintenance, run
bun run check:earnings-provenance(Python 3 required) to compare embedded institution earnings metadata with the official dictionary. Pass a local XLSX path to reuse a download; requests never fetch the dictionary.
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search US colleges and compare historical admissions, costs and aid using public federal data.
College Scorecard MCP — US Department of Education College Scorecard API
Higher education data: tuition, graduation rates, and earnings
US K-12 schools, districts, and colleges from federal data: enrollment, outcomes, finances.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceQuery SEC EDGAR filings, XBRL financials, and company data through MCP.811 npm12Apache 2.0
- AlicenseNot gradedqualityBmaintenanceCollege Scorecard MCP — US Department of Education College Scorecard API83 npmMIT
- AlicenseAqualityDmaintenanceMCP server to query UK higher-education open data including National Student Survey results, student outcomes, and graduate earnings. Data is downloaded locally from official sources and compared against benchmarks.5MIT
- AlicenseAqualityCmaintenanceMCP server providing U.S. college ROI data (30-year NPV, major ROI, best-value rankings, and out-of-state tuition penalty) by wrapping a free, keyless API.7503 npmMIT