HackList

hacklist-mcp

An MCP server that gives Claude and ChatGPT live access to HackList, the directory of AI and Web3 hackathons, grants, bounties and programs.

Ask things like:

• "What should I enter this month? I write Solidity and Python, build agents, I'm in Nigeria and can't travel."
• "When was the Qloo hackathon posted, and what's the actual cash prize?"
• "Anything new on HackList this week over $10k?"
• "Find ZK or privacy hackathons closing in the next 10 days."

Why it isn't just a scraper

HackList lists everything. This server tells you which listings are worth your weekend:

Problem on the raw list	What the server does
Same event listed twice (Amazon, GitLab, OpenCV, GenAI Works…)	Detects duplicates by title, organizer, deadline and apply link, and collapses them
"$190,000 total value" that is mostly AWS credits	Separates cash from credits clause by clause; headline shows the cash
₹, USDC, USDT, € prizes you can't compare	Converts to an approximate USD figure (original text always kept)
Events you can't actually enter	Flags students-only, region-locked, in-person-only, partners-only and application-gated events, and drops them from recommendations
"Build an AI app that solves real-world problems"	Scores each brief for how generic it is (0 = specific, 1 = generic) and lists the concrete hooks: named APIs, datasets, scoring metrics, tracks
Rolling grants and bounties with no deadline	Kept as open ("no fixed deadline") and ranked fairly instead of being dropped or buried

best_opportunities combines all of that with your skills and constraints and explains every pick (why) and every risk (watch_outs).

Tools

Tool	What it does
best_opportunities	Ranks open opportunities for a builder (skills, interests, country, student, can travel, cash only). Down-ranks generic briefs, removes ineligible ones, explains each pick.
search_opportunities	Keyword search with filters: type, AI/Web3, online/in-person/hybrid, min prize, cash only, closes within N days, updated within N days, include closed.
get_opportunity	Full detail for one listing by HackList URL, id or title: brief, prize (USD estimate, cash vs credits), deadline and days left, posted/updated date, apply link, eligibility, duplicates.
whats_new	Listings posted or updated in the last N days.
closing_soon	Open listings ending within N days, soonest first.
hacklist_overview	Counts, cash prize total, biggest prizes, duplicate groups, data coverage. refresh: true re-fetches.
search / fetch	The two tools ChatGPT connectors and deep research expect.

All tools are read-only.

Install

Claude and ChatGPT on the web (no install)

A hosted server is live, so on claude.ai and chatgpt.com you only paste one URL:

https://hacklist-mcp.samuelsuccess234.workers.dev/mcp

claude.ai (also syncs to the Claude desktop and mobile apps)

1. Open Settings → Connectors and click Add custom connector.
2. Name: HackList. Remote MCP server URL: the URL above. Click Add.
3. In a chat, open the tools menu next to the message box and make sure HackList is turned on.
4. Ask: "What hackathons are open right now?" or "What should I enter this month? I write Solidity and I'm in Nigeria."

ChatGPT

1. Open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
2. Back in Apps & Connectors, click Create.
3. Name: HackList. MCP server URL: the URL above. Authentication: No authentication. Tick the box saying you trust this application, then click Create.
4. In a chat, click +, choose Developer mode, enable HackList, and ask your question.

ChatGPT's deep research uses the search and fetch tools; normal chats can call all of them.

If you can't find the connector option, check your plan: Claude and ChatGPT decide which plans can add custom connectors, and that changes over time.

Claude Desktop (local, stdio)

Requires Node 18.17+.

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hacklist": {
      "command": "npx",
      "args": ["-y", "hacklist-mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http hacklist https://hacklist-mcp.samuelsuccess234.workers.dev/mcp
# or run it locally:
claude mcp add hacklist -- npx -y hacklist-mcp

Cursor, Windsurf, other stdio clients

Same command: npx -y hacklist-mcp.

Self-hosting the connector

To run your own copy instead of the hosted URL, deploy the HTTP mode or the Cloudflare Worker (below) and use https://your-host/mcp in the steps above.

Run the HTTP server

npm install && npm run build
PORT=3000 npm run start:http          # serves POST /mcp and GET /healthz

Stateless Streamable HTTP, so it scales horizontally and works behind any load balancer. One HackList snapshot is shared across requests.

Deploy anywhere that runs Docker:

docker build -t hacklist-mcp .
docker run -p 3000:3000 hacklist-mcp

Works as-is on Render, Railway, Fly.io or Cloud Run (all give you HTTPS). To keep it private, set HACKLIST_MCP_TOKEN and the server will require Authorization: Bearer <token>. Leave it unset for a public, no-auth connector.

Cloudflare Workers

src/worker.ts serves the same endpoints without Express or a disk cache:

npx wrangler login
npm run dev:worker                    # local, http://localhost:8787/mcp
npm run deploy:worker                 # https://hacklist-mcp.<your-subdomain>.workers.dev/mcp
npx wrangler secret put HACKLIST_MCP_TOKEN   # optional, same bearer-token behaviour

The HackList snapshot is cached per Worker instance, so a cold instance's first call re-fetches the feed (about 2s). If the free plan's 10ms CPU limit trips on cold starts (Exceeded CPU Limit in npx wrangler tail), move to Workers Paid.

Check it's reading HackList correctly

npm run check

Prints whether the official feed was used, how many listings were loaded vs. what HackList says is open, and how often each field was filled.

Configuration

Env var	Default	Purpose
PORT	3000	HTTP mode port
HACKLIST_MCP_TOKEN	unset	Require a bearer token in HTTP mode
HACKLIST_LIST_TTL_MS	1200000 (20 min)	How long a snapshot stays fresh
HACKLIST_MAX_DETAIL_FETCHES	260	Cap on detail pages fetched per refresh
HACKLIST_CACHE_DIR	~/.cache/hacklist-mcp	Disk cache for detail pages (restarts are instant)
HACKLIST_BASE_URL	https://hacklist.io	Override for testing or a mirror
HACKLIST_FEED_URL	/api/opportunities	Feed path or full URL

How it gets the data

1. Official feed (GET https://hacklist.io/api/opportunities), provided by HackList. One request per refresh (cached 20 min) returns every open hackathon, program, grant and bounty, with each listing's real created_at posting date.
2. Fallback: if the feed is down or returns something unexpected, the server reads the public pages instead (homepage, /sitemap.xml, detail pages), keyed off visible labels so cosmetic redesigns don't break it.
3. Closed listings (include_closed: true) come from the sitemap and detail pages, since the feed only lists open ones.

hacklist_overview and every result report data_source (feed or pages) and data_as_of (when HackList generated the feed).

Thanks to HackList (@0xbeni, Telegram) for exposing the feed. This project is not affiliated with HackList.

Develop

npm install
npm test        # 19 tests: feed + page parsers, fallback, prize/eligibility/duplicate logic, full MCP round-trips
npm run dev     # stdio server via tsx

Limits

• Prize USD figures are estimates (fixed approximate FX rates). The original prize text is always returned alongside.
• Prizes paid in crypto (ETH, SOL…) get no USD estimate because the price moves; they're labeled instead.
• In page-scraping fallback mode, programs, grants and bounties beyond the homepage's first page may be missing (the sitemap only covers hackathons).
• "Generic" scoring is heuristic. It's tuned to separate briefs like "build any AI app" from briefs like "detect 12 knee MRI abnormalities, scored by AUC", and include_generic: true turns the penalty off.

MIT licensed.