Opportunity MCP

Opportunity MCP

A Model Context Protocol server that lets any AI assistant search youth opportunities — scholarships, fellowships, internships, conferences, and exchange programs — aggregated live from leading opportunity-discovery sites.

[PyPI version] [Python] [License: MIT] [Tests] [Refresh cron] [MCP Registry]

Status: alpha (v0.1.x). Schema, tool surface, and source list may change as adapters mature. Pin to a minor version in production.

Overview

Students who depend on third-party scholarship-aggregator sites typically open ten or more tabs, sift through dozens of irrelevant posts, and copy deadlines into a personal spreadsheet — only to miss the application window because no aggregator offers reliable deadline tracking. Opportunity MCP collapses that workflow into a single conversational query.

You: Find fully-funded master's scholarships in Europe with deadlines in the next 60 days, eligible for Pakistani citizens.

Claude: (Returns a deduplicated, structured list pulled live from the indexed sources, sorted by deadline, each linking back to the original article.)

The server runs locally over stdio, ships an SQLite + FTS5 index that refreshes every six hours via CI, and is distributed through PyPI, the official MCP Registry, and Smithery.

Distribution channels

Installation

Claude Desktop

pip install opportunity-mcpopportunity-mcp-refresh           # build the local index (one-off, ~30 seconds)

Add the following to claude_desktop_config.json:

{  "mcpServers": {    "opportunities": {      "command": "opportunity-mcp"    }  }}

Restart Claude Desktop. The six tools below become available to the model.

Cursor, Windsurf, Continue, and other MCP clients

Most clients use the same mcpServers shape. Point the command at opportunity-mcp (after pip install) or use uvx for zero-install:

{  "mcpServers": {    "opportunities": {      "command": "uvx",      "args": ["opportunity-mcp"]    }  }}

Smithery (one-click install)

https://smithery.ai/server/sayedhusnainhader/opportunity-mcp — Smithery handles the install command for you.

From source

git clone https://github.com/revolutionarybukhari/opportunity-mcpcd opportunity-mcpuv sync                           # or: pip install -e ".[dev]"uv run opportunity-mcp-refreshuv run opportunity-mcp            # speaks MCP over stdio

Tools

The server exposes six tools. Each accepts JSON arguments and returns Pydantic-typed results.

type is one of scholarship, fellowship, internship, conference, exchange, competition, grant, award, or other.

Indexed sources

Verified live against each site's RSS feed.

Per-source robots.txt compliance, ToS notes, and CI quirks are documented in docs/SOURCES.md.

Example prompts

Find fully-funded master's scholarships in Europe with deadlines in the next 60 days.
What conferences are happening in Africa in the next three months?
List the ten newest internships indexed today.
Show me everything closing in the next seven days that an undergraduate could apply to.
Get full details for opportunity 7733b95a81e3239d.

Architecture

AI client  ──MCP──▶  FastMCP server  ──▶  SQLite + FTS5  ◀──  refresh job  ──▶  source adapters  ──▶  opportunity sites

Two clean separations of concern:

1. Adapters know how to read one site and produce raw Opportunity objects (Pydantic-validated).
2. The query engine knows nothing about sites — it searches a normalized index.

Adding a new source is typically a fifty-line pull request. See docs/ADAPTER_GUIDE.md. Full architecture rationale is in docs/ARCHITECTURE.md.

Privacy & ethics

• No user tracking. All queries are processed locally; nothing leaves the user's machine except the periodic source-site refresh.
• All indexed data is public. Summaries are capped at 500 characters and every record links back to the originating article.
• Polite identification. The HTTP User-Agent includes the project URL so site owners can reach us directly.
• Conservative refresh cadence. Sources are polled at most every six hours, via CI — never on user query.
• Source removals on request are honored within 24 hours, with no negotiation.
• robots.txt is respected by every adapter prior to fetching.

Roadmap

• Phase 2 — country-, level-, and language-aware extraction (currently delegated to the AI client).
• Phase 3 — first HTML adapter (Youth Opportunities), broader Tier-2/Tier-4 source coverage.
• Phase 4 — hosted Streamable-HTTP endpoint for clients that prefer remote MCP servers.
• Phase 5 — optional weekly digest by saved profile.

Open issues with the add a source label are good first contributions.

Contributing

Pull requests are welcome. The fastest way to help is to add a source we do not yet index — read docs/ADAPTER_GUIDE.md and open a PR. See docs/CONTRIBUTING.md for development setup, testing conventions, and the code-of-conduct expectations.

git clone https://github.com/revolutionarybukhari/opportunity-mcpcd opportunity-mcpuv syncuv run pytestuv run ruff check .

License

MIT © Opportunity MCP Contributors.