<p align="center"> <img src="assets/campusintel-readme-banner.png" alt="CampusIntel MCP" width="100%"> </p>

<p align="center"> <a href="https://github.com/acestein13/campusintel-mcp/actions/workflows/ci.yml"><img src="https://github.com/acestein13/campusintel-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB" alt="Python 3.11+"> <img src="https://img.shields.io/badge/MCP-2.x-45d6c4" alt="MCP 2.x"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a> </p>

CampusIntel MCP

CampusIntel is a Model Context Protocol server that gives AI assistants structured access to university research, researchers, academic programs, and institutional data. It combines the OpenAlex scholarly knowledge graph with the U.S. Department of Education's College Scorecard while preserving source links and limitations in every result.

The project is designed for research discovery and university investigation—not admissions predictions or one-number rankings.

What is an MCP server?

An MCP server is a small piece of infrastructure that lets an AI host—such as Claude Desktop, VS Code, or the MCP Inspector—call reliable tools instead of guessing. Think of it as a secure adapter between an AI assistant and outside data sources.

CampusIntel is not a college-advice chatbot and it does not use an LLM to invent university facts. It exposes clearly named functions such as search_research and list_academic_programs. The AI host decides when to call them; CampusIntel validates the request, obtains live data from the appropriate source, and returns structured, source-linked results the host can explain to the user.

How a request works

sequenceDiagram
    participant User
    participant Host as AI host
    participant CI as CampusIntel
    participant Data as Data provider
    User->>Host: "Find AI-safety research at a university"
    Host->>CI: Call a typed MCP tool
    CI->>CI: Validate inputs and check cache
    CI->>Data: Request live, scoped data
    Data-->>CI: Structured response
    CI-->>Host: Normalized result with source URL
    Host-->>User: Grounded answer with limitations

For example, an AI host first calls search_universities to resolve a name to an OpenAlex institution ID. It then passes that ID to search_research or find_topic_researchers. This two-step pattern avoids ambiguous name matching and keeps research results tied to a specific institution.

What it can do

Tool	Purpose	Data source
search_universities	Resolve university names to stable OpenAlex IDs	OpenAlex
get_university_profile	Research footprint plus optional U.S. federal metrics	Both
search_research	Find papers by topic, university, year, and open-access status	OpenAlex
search_researchers	Find researchers by name and affiliation	OpenAlex
find_topic_researchers	Discover researchers through relevant university papers	OpenAlex
search_us_colleges	Find U.S. colleges, costs, outcomes, and Scorecard IDs	College Scorecard
list_academic_programs	Filter fields of study and credential levels	College Scorecard
compare_universities	Produce a source-aware comparison for two to five schools	Both
health_check	Verify local provider configuration without exposing secrets	Local

CampusIntel also exposes a campusintel://methodology resource and a reusable research_university_fit prompt.

Architecture

flowchart TD
    Host["AI host or MCP Inspector"] --> Server["CampusIntel MCP server"]
    Server --> Service["Validation and orchestration"]
    Service --> OA["OpenAlex client"]
    Service --> CS["College Scorecard client"]
    OA --> Research["Institutions, works, authors"]
    CS --> Federal["Programs, costs, outcomes"]

The provider clients include typed normalization, bounded retries, timeouts, and an in-memory TTL cache. Cross-source matching is intentionally isolated in the service layer, so raw provider data and inferred relationships are never confused.

Where the information comes from

Source	CampusIntel uses it for	Important context
OpenAlex	Global universities, scholarly papers, authors, affiliations, topics, citations, and open-access links	It is an open scholarly index. Coverage and citation counts vary by field and publication age.
College Scorecard	U.S. programs, enrollment, cost, admissions, completion, and earnings fields	It is published by the U.S. Department of Education. Its latest metrics can come from different reporting cohorts.

CampusIntel does not scrape faculty pages, use private student data, or claim it can predict an applicant's admissions outcome. It preserves the provider URL with each returned record so a user can check the primary data before relying on it.

Quick start

1. Install

Install uv, then clone and sync the project:

git clone https://github.com/acestein13/campusintel-mcp.git
cd campusintel-mcp
uv sync --all-extras --dev

No virtual-environment activation is required when commands begin with uv run.

2. Configure provider keys

Copy .env.example to .env, then add your keys:

• OPENALEX_API_KEY: recommended for normal use; create a free key in OpenAlex settings.
• COLLEGE_SCORECARD_API_KEY: required for U.S. institutional and academic-program tools; request a free data.gov API key.

OpenAlex supports limited keyless demonstration requests. CampusIntel still works without a College Scorecard key, but the U.S. college and program tools will return a clear configuration error and profiles will omit Scorecard enrichment.

Keep keys private

Never put a real key in README.md, source code, a committed .env file, a screenshot, or an MCP configuration file you plan to share. This repository includes .env.example with blank placeholders only, and .gitignore excludes .env.

Set OPENALEX_API_KEY and COLLEGE_SCORECARD_API_KEY as local environment variables, or place their values only in your uncommitted .env file, then run uv run campusintel-mcp. health_check reports only whether a provider is configured; it never returns secret values.

3. Test with MCP Inspector

macOS/Linux:

set -a && source .env && set +a
uv run mcp dev src/campusintel_mcp/server.py

Windows PowerShell:

uv run mcp dev src/campusintel_mcp/server.py

Before running the Windows command, define OPENALEX_API_KEY and COLLEGE_SCORECARD_API_KEY in your local PowerShell session or in an uncommitted .env file.

The Inspector opens in a browser. Start with search_universities, retain the returned OpenAlex ID, and pass it into the research tools.

Connect an MCP host

The repository includes ready-to-edit examples for Claude Desktop and VS Code. Replace the absolute path and keep real keys outside files you commit or share.

A generic stdio entry is:

{
  "command": "uv",
  "args": ["--directory", "/ABSOLUTE/PATH/TO/campusintel-mcp", "run", "campusintel-mcp"]
}

Streamable HTTP and Docker

Local stdio is the default. To run the same server over Streamable HTTP:

CAMPUSINTEL_TRANSPORT=streamable-http uv run campusintel-mcp

The endpoint is http://127.0.0.1:8000/mcp. Host and port can be changed with CAMPUSINTEL_HOST and CAMPUSINTEL_PORT.

docker build -t campusintel-mcp .
docker run --rm -p 8000:8000 \
  -e OPENALEX_API_KEY \
  -e COLLEGE_SCORECARD_API_KEY \
  campusintel-mcp

Example workflow

To investigate AI safety research at a university, an MCP client can:

1. Call search_universities(query="Carnegie Mellon University", country_code="US").
2. Pass the returned ID into search_research(topic="AI safety", institution_id="I...", from_year=2022).
3. Call find_topic_researchers with the same topic and institution ID.
4. Resolve the federal school ID with search_us_colleges, then call list_academic_programs(query="computer science", credential_level=3).
5. Preserve the returned source URLs and methodology notes in the final answer.

Example prompts for an AI host

• “Compare recent robotics research at Georgia Tech and Carnegie Mellon. Link the source papers.”
• “Find researchers working on AI safety at this university, then show the papers that made each person relevant.”
• “For this U.S. school, list bachelor’s-level computer science programs and clearly separate program data from research metrics.”

The host should call the tools, not assume that a university name is enough to identify a single institution. CampusIntel's returned IDs make later calls precise and reproducible.

Tool behavior and safeguards

• Input validation: empty queries, invalid years, duplicate comparison IDs, and invalid credential levels are rejected with an actionable tool error.
• Reliable requests: provider calls use timeouts, bounded retries for transient failures, and a short-lived in-memory cache to reduce repeated requests.
• Transparent missing data: unavailable fields remain null; CampusIntel does not fill them with estimates or zeros.
• Source-aware enrichment: U.S. federal metrics are added only when an OpenAlex institution can be reasonably name-matched to a Scorecard record, and the result is labeled accordingly.
• No hidden rankings: citation counts, h-index values, and outcomes are descriptive context, never an overall university score or admissions prediction.

Data responsibility

• OpenAlex metrics reflect an indexed scholarly corpus; citation volume varies heavily by field, publication age, and coverage.
• College Scorecard latest fields can come from different reporting cohorts.
• Topic-researcher results are ranked within a relevance sample. They are not exhaustive faculty directories or judgments of researcher quality.
• A missing value remains null; CampusIntel does not estimate it.
• Name-based OpenAlex-to-Scorecard enrichment is labeled and should be verified before a consequential decision.

See the in-server campusintel://methodology resource for the same guidance in MCP clients.

Development

uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pytest --cov

The test suite uses mocked HTTP transports plus the MCP SDK's in-memory client. CI runs formatting, linting, strict type checking, and tests on Python 3.11 and 3.12.

License

Released under the MIT License.