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:

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

Related MCP server: bounty-mcp

Tools

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

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.