HackList

hacklist-mcp

一个 MCP 服务，让 Claude 和 ChatGPT 能够实时访问 HackList，这是一个 AI 和 Web3 黑客松、资助、悬赏及计划的目录。

可以询问：

• “这个月我应该参加什么？我会写 Solidity 和 Python、开发 Agent，人在尼日利亚，而且无法出行。”
• “Qloo 黑客松是什么时候发布的？实际现金奖金是多少？”
• “本周 HackList 上有什么新活动，奖金超过 10k 美元？”
• “查找 10 天内截止报名的 ZK 或隐私黑客松。”

它不只是一个抓取器的原因

HackList 会列出所有活动。这个服务会告诉你哪些活动值得占用一个周末：

原始列表中的问题	服务会做什么
同一活动被列出两次（Amazon、GitLab、OpenCV、GenAI Works……）	根据标题、组织方、截止日期和申请链接检测重复项，并将其合并
“总价值 190,000 美元”，其中大部分其实是 AWS 额度	按条款区分现金与额度；标题中显示现金金额
₹、USDC、USDT、€ 奖金，难以比较	换算为大致的美元金额（始终保留原文）
你实际上无法参加的活动	标记仅限学生、地区限制、仅限线下、仅限合作伙伴及需申请的活动，并从推荐中剔除
“开发一款能解决现实问题的 AI 应用”	为每个赛题评估其泛化程度（0 = 具体，1 = 泛化），并列出具体切入点：指定的 API、数据集、评分指标和赛道
没有截止日期的长期资助和悬赏	保留为开放状态（“无固定截止日期”），并公平排名，而不是将其剔除或埋没

best_opportunities 会结合所有这些信息以及你的技能和限制条件，解释每项推荐的理由（why）和风险（watch_outs）。

工具

工具	功能
best_opportunities	为开发者排列开放机会的优先级（技能、兴趣、国家、学生身份、能否出行、仅限现金）。降低泛化赛题的排名，剔除不符合资格的机会，并解释每项推荐。
search_opportunities	按关键词搜索并筛选：类型、AI/Web3、线上/线下/混合形式、最低奖金、仅限现金、N 天内截止、N 天内更新、包括已结束的活动。
get_opportunity	根据 HackList URL、id 或标题获取某个列表项的完整详情：赛题、奖金（美元估算、现金与额度）、截止日期和剩余天数、发布日期/更新日期、申请链接、资格要求、重复项。
whats_new	过去 N 天内发布或更新的列表项。
closing_soon	N 天内结束的开放列表项，按截止时间从近到远排列。
hacklist_overview	数量、现金奖金总额、最高奖金、重复项组、数据覆盖情况。refresh: true 会重新获取数据。
search / fetch	ChatGPT 连接器和深度研究所需的两个工具。

所有工具均为只读。

安装

在网页端使用 Claude 和 ChatGPT（无需安装）

托管服务已经上线，因此在 claude.ai 和 chatgpt.com 上只需粘贴一个 URL：

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

claude.ai（也会同步到 Claude 桌面端和移动应用）

1. 打开 Settings → Connectors，然后点击 Add custom connector。
2. 名称：HackList。远程 MCP 服务 URL：上方的 URL。点击 Add。
3. 在聊天中，打开消息框旁边的工具菜单，并确保已启用 HackList。
4. 提问：“现在有哪些黑客松正在开放报名？” 或 “这个月我应该参加什么？我会写 Solidity，而且人在尼日利亚。”

ChatGPT

1. 打开 Settings → Apps & Connectors → Advanced settings，然后开启 Developer mode。
2. 返回 Apps & Connectors，点击 Create。
3. 名称：HackList。MCP 服务 URL：上方的 URL。身份验证：No authentication。勾选表示你信任此应用的方框，然后点击 Create。
4. 在聊天中，点击 +，选择 Developer mode，启用 HackList，然后提问。

ChatGPT 的深度研究会使用 search 和 fetch 工具；普通聊天可以调用所有工具。

如果找不到连接器选项，请检查你的套餐：Claude 和 ChatGPT 会决定哪些套餐可以添加自定义连接器，而且规则会随时间变化。

Claude Desktop（本地，stdio）

需要 Node 18.17+。

添加到 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 及其他 stdio 客户端

使用相同的命令：npx -y hacklist-mcp。

自托管连接器

若要运行自己的副本，而不是使用托管 URL，请部署 HTTP 模式或 Cloudflare Worker（见下文），并在上述步骤中使用 https://your-host/mcp。

运行 HTTP 服务

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

采用无状态 Streamable HTTP，因此可以水平扩展，并可在任何负载均衡器后运行。所有请求共享同一份 HackList 快照。

可部署到任何支持运行 Docker 的平台：

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

可直接在 Render、Railway、Fly.io 或 Cloud Run 上运行（这些平台都会提供 HTTPS）。若要保持私有，请设置 HACKLIST_MCP_TOKEN，服务将要求提供 Authorization: Bearer <token>。不设置该变量，则连接器公开且无需身份验证。

Cloudflare Workers

src/worker.ts 提供相同的端点，不需要 Express 或磁盘缓存：

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

HackList 快照会按 Worker 实例缓存，因此冷启动实例的首次调用会重新获取数据源（约 2 秒）。如果免费计划的 10ms CPU 限制在冷启动时触发（npx wrangler tail 中显示 Exceeded CPU Limit），请升级到 Workers Paid。

检查是否正确读取 HackList

npm run check

显示是否使用了官方数据源、加载了多少条列表（与 HackList 声称开放的数量对比），以及各字段的填充频率。

配置

环境变量	默认值	用途
PORT	3000	HTTP 模式端口
HACKLIST_MCP_TOKEN	未设置	在 HTTP 模式下要求提供 bearer 令牌
HACKLIST_LIST_TTL_MS	1200000（20 分钟）	快照保持最新的时长
HACKLIST_MAX_DETAIL_FETCHES	260	每次刷新获取的详情页上限
HACKLIST_CACHE_DIR	~/.cache/hacklist-mcp	详情页磁盘缓存（重启后可立即使用）
HACKLIST_BASE_URL	https://hacklist.io	用于测试或镜像的覆盖值
HACKLIST_FEED_URL	/api/opportunities	数据源路径或完整 URL

数据获取方式

1. 官方数据源（GET https://hacklist.io/api/opportunities），由 HackList 提供。每次刷新请求一次（缓存 20 分钟），即可获取所有开放的黑客马拉松、项目、资助和赏金，以及每条列表真实的 created_at 发布日期。
2. **备用方式：**如果数据源不可用或返回异常内容，服务会改为读取公开页面（主页、/sitemap.xml 和详情页），并依据可见标签进行解析，因此外观改版不会导致解析失效。
3. 已关闭的列表（include_closed: true）来自站点地图和详情页，因为数据源只列出开放项目。

hacklist_overview 和每条结果都会报告 data_source（feed 或 pages）以及 data_as_of（HackList 生成数据源的时间）。

感谢 HackList（@0xbeni、Telegram）开放数据源。本项目与 HackList 无关。

开发

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

限制

• 奖金的美元金额为估算值（采用固定的近似汇率）。始终会同时返回原始奖金文本。
• 以加密货币（ETH、SOL……）支付的奖金不会估算美元金额，因为币价会变动；系统会改为标注币种。
• 在页面抓取备用模式下，主页第一页以外的项目、资助和赏金可能会遗漏（站点地图仅涵盖黑客马拉松）。
• “Generic”评分采用启发式方法，旨在区分“构建任意 AI 应用”这类简报与“检测 12 种膝关节 MRI 异常，并按 AUC 评分”这类简报；设置 include_generic: true 可关闭此项惩罚。

采用 MIT 许可证。