Unstop Server

unstop-mcp is a Python Model Context Protocol (MCP) server for discovering Unstop hackathons.

It exposes:

• MCP tools for searching hackathons, fetching event details, running location-based discovery, and managing cache state
• MCP resources for read-only snapshots and per-hackathon lookups
• MCP prompts that help an LLM plan searches, compare hackathons, and recommend relevant events

This repository is now MCP-first. The old direct-import Python wrapper API is not the supported public interface anymore.

What It Supports

• stdio transport only
• Unstop hackathons only in v1
• Automatic caching of open hackathons for fast repeated lookups
• Detail enrichment for descriptions, rounds, contacts, registration counts, and views
• Optional location-based search using geocoding
• Deterministic unit tests with mocked upstream behavior
• Optional live smoke tests kept separate from the default suite

Requirements

• Python 3.12+
• uv recommended for local development
• Network access for real Unstop calls

Installation

Option 1: uv workflow

git clone https://github.com/your-org/unstop-mcp.git
cd unstop-mcp
uv venv
source .venv/bin/activate
uv pip install -e .

Option 2: plain pip

git clone https://github.com/your-org/unstop-mcp.git
cd unstop-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Verify the install

unstop-mcp --help

You should see the stdio transport option.

Running The Server

Run the server locally over stdio:

unstop-mcp

Equivalent module form:

python -m unstop_mcp

The server intentionally supports only:

unstop-mcp --transport stdio

MCP Surface

Tools

search_hackathons

Search Unstop hackathons with filters, sorting, pagination, and optional cache usage.

Arguments:

• oppstatus: open | recent | expired | closed
• region: online | offline
• payment: paid | unpaid
• teamsize: 1 | 2 | 3
• usertype: college_students | fresher | professionals | school_students
• sort: prize | days_left
• direction: asc | desc
• search: free-text keyword search
• page: >= 1
• per_page: 1-100
• use_cache: true | false

Returns a structured object with:

• items: normalized hackathon summaries
• pagination: total/current page/last page/per-page/has-more
• cache: cache freshness metadata
• applied_filters: the validated input used for the call

get_hackathon_details

Fetch full details for a single hackathon by numeric ID.

Arguments:

• hackathon_id

Returns:

• item: normalized detail view
• cache: metadata describing current server cache state

search_hackathons_by_location

Find offline hackathons near a location using geocoding and radius filtering.

Arguments:

• location
• radius_km
• region
• payment
• teamsize
• usertype
• search
• sort: prize | days_left | distance
• direction
• page
• per_page

Returns the same normalized structure as search_hackathons, plus:

• location.search_location
• location.search_radius_km
• location.search_coordinates

refresh_cache

Force a rebuild of the cached open-hackathon dataset.

Returns:

• cache

get_cache_info

Inspect cache state without rebuilding the full dataset.

Returns:

• cache

Resources

unstop://cache/info

Read-only JSON view of cache freshness, TTL, and item counts.

unstop://hackathons/open

Read-only JSON snapshot of all cached open hackathons.

unstop://hackathons/{hackathon_id}

Read-only JSON detail view for a specific hackathon. The server serves cached data when possible and falls back to a direct detail fetch when needed.

Prompts

find_relevant_hackathons

Guides an LLM to gather missing user preferences, call the right search tool, and summarize the best matches.

Arguments:

• user_goal

compare_hackathons

Guides an LLM to fetch multiple hackathons and compare them.

Arguments:

• hackathon_ids

plan_hackathon_search

Guides an LLM on which tools and resources to call, in what order, for a discovery task.

Arguments:

• user_request

Output Shape

Tool and resource results are normalized into stable JSON-friendly fields rather than returning raw upstream Unstop payloads as the primary contract.

Each hackathon item includes:

• id
• title
• status
• region
• is_paid
• public_url
• description
• prize_amount
• prize_summary
• filters
• required_skills
• organisation
• address
• registration
• rounds
• contacts
• distance_km when applicable

This keeps the MCP contract predictable even if upstream response shapes vary.

Client Setup

Generic MCP client

Point your MCP client at this command:

unstop-mcp

If your client needs an absolute command path, use the one from your environment, for example:

/absolute/path/to/.venv/bin/unstop-mcp

Claude Desktop

Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "unstop": {
      "command": "/absolute/path/to/.venv/bin/unstop-mcp",
      "args": []
    }
  }
}

Codex

Configure a local MCP server entry that launches:

{
  "command": "/absolute/path/to/.venv/bin/unstop-mcp",
  "args": []
}

If your Codex setup manages MCP servers through a separate config file or UI, use the same command and no extra arguments.

Development

Project layout

• src/unstop_mcp/server.py: FastMCP server definition and MCP registration
• src/unstop_mcp/service.py: Unstop fetching, caching, normalization, and geocoding logic
• src/unstop_mcp/schemas.py: validated inputs and normalized output models
• src/unstop_mcp/config.py: environment-driven runtime configuration
• tests/: unit, MCP registration, stdio smoke, and optional live tests

Environment variables

These are optional:

• UNSTOP_MCP_TIMEOUT
• UNSTOP_MCP_MAX_RETRIES
• UNSTOP_MCP_RETRY_DELAY
• UNSTOP_MCP_CACHE_TTL_SECONDS
• UNSTOP_MCP_DETAIL_WORKERS
• UNSTOP_MCP_DETAIL_DELAY
• UNSTOP_MCP_GEOCACHE_PATH
• UNSTOP_MCP_USER_AGENT

How caching works

• Searches for open hackathons can use an in-memory snapshot instead of hitting Unstop on every call
• The snapshot is rebuilt automatically when stale
• refresh_cache forces an immediate rebuild
• The geocode cache is persisted to disk so repeated location lookups do not re-query the geocoder unnecessarily

Geocoding behavior

• Location search depends on geopy
• Offline hackathons with explicit coordinates are used directly
• When coordinates are missing, the server tries multiple address variants and caches the result
• Online-only hackathons are excluded from radius searches unless the query explicitly requests region="online"

Testing

Run the default test suite:

python -m pytest -q

What the default suite covers:

• validation and parsing
• normalized search responses
• cache metadata and staleness behavior
• location filtering
• MCP tool/resource/prompt registration
• basic end-to-end stdio startup and tool listing

Optional live smoke tests

These are excluded by default:

UNSTOP_MCP_RUN_LIVE_TESTS=1 python -m pytest -q -m live

Use live tests only when you want to verify the current Unstop integration against the real network.

Local Validation

Useful local checks:

python -m pytest -q
python -m unstop_mcp --help

If you already use an MCP Inspector, point it at the local unstop-mcp command and stdio transport to inspect registered tools, resources, and prompts interactively.

Error Handling

The server validates inputs before making upstream calls.

Common failure cases:

• invalid enum values such as unsupported oppstatus or sort
• empty or unresolvable location input
• transient or permanent upstream Unstop failures
• missing geocoding support for location search

When possible, tool failures are surfaced as clear MCP-facing validation or request errors.

Limitations

• stdio only in v1
• hackathons only in v1
• upstream Unstop fields and availability can change
• location accuracy depends on source address quality and geocoding quality
• cache refresh can take longer than simple detail fetches because it enriches open hackathons in bulk

Extending The Server

If you want to add more Unstop opportunity types later, keep this split:

• add new upstream fetch/parse logic in service.py
• define new validated contracts in schemas.py
• register new MCP surfaces in server.py

That keeps transport concerns separate from domain logic.

License

MIT