grantsgov-mcp-server

---

概述

Grants.gov 上的美国联邦资助机会，涵盖各机构的预测发布、已发布、已关闭和已归档公告。可按关键词、机构、申请人类型、资助类别、援助项目或截止日期范围搜索，然后读取完整记录，包括资助金额范围、资格要求、重要日期、机构联系人和 NOFO 附件。无需 API 密钥。

工具

工具	描述
grantsgov_search_opportunities	按关键词和筛选条件搜索机会；每行优先显示截止日期和剩余天数，并提供用于缩小范围的分面计数
grantsgov_get_opportunity	按数字 ID 或机会编号读取最多 5 个机会的完整记录
grantsgov_list_reference	列出搜索筛选条件所接受的代码（机构、申请人类型、资助类别和资助工具），以及状态、排序选项和关键词语法

grantsgov-guide 技能介绍资助机会筛选、资格与截止日期审查，以及申请要求。该技能随软件包和插件一同提供，也可通过 MCP 使用 skill://grantsgov-guide/SKILL.md 获取。

功能参考

grantsgov_search_opportunities _工具

• 筛选条件：keyword、statuses（默认值为 forecasted 和 posted）、agencies（代码包含其下属机构）、eligibilities、funding_categories、funding_instruments、assistance_listing（一个 ALN）、opportunity_number（精确匹配）、posted_within_days、closing_within_days
• eligibilities 也会匹配向任何申请人类型开放的机会（代码 99），除非 include_unrestricted 为 false
• 所有关键词词项都必须匹配；用 OR 连接备选项，用引号括起短语，用 NOT 或 -term 排除词项，并在末尾加 * 进行前缀匹配。未分组的 AND/OR 混合表达式或字段前缀（agency:NSF）会失败，并返回 invalid_keyword
• closing_within_days（0–365）按截止日期扫描已发布的机会；它只允许使用 posted 状态和 close_date_asc 排序，而 posted_within_days 不允许与 closed 和 archived 状态同时使用（filter_conflict）。total_count_kind 用于区分扫描不完整时的精确计数和下限；next_offset 只能获取扫描后剩余的匹配项
• 每页最多 100 条（默认 25 条）；limit 接受 1–1,000，超过 100 的值会被限制为 100，并附带提示。使用 next_offset 进行偏移分页；effective_keyword 和 applied_filters 会回显已发送的内容。下属机构分面会统计当前上游查询中每个子树的数量；include_facets: false 会省略分面计数
• 每条记录包含 close_date_kind（fixed、none_listed、placeholder）和 days_until_close，但不包含资助金额。未知代码会导致 unknown_agency、unknown_eligibility 或 unknown_funding_category

---

grantsgov_get_opportunity _工具

• 每个标识符列表最多接受 50 个非空条目，合计最多接受 50 个规范化后的唯一标识符。读取前 5 个标识符，优先读取 ID，再读取编号；剩余队列及其原始区段偏移量由 deferred_ids、deferred_numbers 和可执行的 continuation 携带。编号会在全部四种状态中解析；每次调用中，选中的别名只会获取一次记录
• 未找到的记录或被多个机会共用的编号不会作为错误返回，而是会在 unresolved[] 中标记为 not_found 或 ambiguous（并附带 candidates）
• 记录包含截止日期（预测记录中的日期为估算值，并由 close_date_is_estimate 标记）、资助上限和下限、资助总额、预期资助数量、成本分担、申请人类型及资格说明、援助清单和机构联系人
• 资助和资格字段来自与 doc_type 匹配的概要或预测区块，来源记录在 money_source 中；预测记录还会添加 forecast_estimates
• 独立分页：描述 12,000 个字符、资格说明 6,000 个字符、资助类别说明 2,000 个字符、附件 30 个、申请包 10 个、相关机会 10 个。六个从 0 开始的输入项为 description_offset、eligibility_offset、funding_category_explanation_offset、attachment_offset、application_package_offset 和 related_opportunity_offset（默认值为 0）。每条记录的 pages 会提供完整总数和可执行的单个机会续接项；部分说明会保留 *_truncated，超出范围的分页返回空内容。列出附件时会包含 download_url 和未经修改的上游 created_date
• 若有列出，last_revision_note 和 last_revision_changed 会汇总当前概要或预测内容的最新修订信息。已更改的名称会映射到公开字段；未知名称会保留 upstream: 前缀。缺少元数据并不表示没有内容更改

---

grantsgov_list_reference _工具

• topic：agencies、eligibilities、funding_categories、funding_instruments、statuses、sort_options 或 keyword_syntax
• 代码来自 Grants.gov 的实时快照，缓存 24 小时，并通过 snapshot_date 标注日期；每个代码均包含 open_count（预测中和已发布）和 total_count（statuses 仅包含 total_count）
• 每页最多 100 条（默认 50 条）；limit 接受 1–1,000，超过 100 的值会被限制为 100，并显示提示。过滤条件在分页前应用；continuation 会保留下一次调用的完整参数
• 刷新失败时，可提供已过期的数据，并通过 reference_cache 披露数据过期状态、失败原因和重试时间。使用该词汇的搜索也会披露相同的降级情况和快照时间戳
• agencies 默认列出顶层机构；parent_code 列出某个机构下的所有代码；name_contains 可匹配任意主题中的标签和代码（对 agencies 而言，适用于所有层级）
• parent_code 与其他主题一起使用时会以 filter_not_applicable 失败；未知代码会以 unknown_parent_code 失败

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Grants.gov 专属功能：

• 列表输入接受单个完整字符串或数组；空值和空成员会被视为未设置。字符串不会按逗号、空格或换行拆分
• 无需密钥的 Grants.gov REST API 客户端（search2、fetchOpportunity），支持重试，且每个进程最多并发 4 个上游请求
• 将输入映射为 Grants.gov 的预期读取形式：裸关键词使用 AND 连接，带连字符的词元（COVID-19、K-12）按词组匹配，机构代码会展开为其下属机构子树，机会编号按字面匹配，过滤代码会根据实时词汇表进行验证
• 截止日期按 Grants.gov 发布时使用的时区——美国东部时间——从今天起计算；远期占位关闭日期会标记为 placeholder，而不会作为截止日期报告
• 解码人类可读字段中的 HTML5 实体；将叙述性 HTML 转换为纯文本，同时保留表格单元格和行的边界。在 content[] 中，机构说明文字呈现为普通文本，标识符保留代码样式，多行字段呈现为引用块，行内文本会合并为一行

面向 Agent 的输出：

• 回显实际运行的内容：effective_keyword 和 applied_filters，包括默认状态、展开后的机构过滤条件，以及新增的代码 99
• 可区分字段：close_date_kind、doc_type、money_source 和 unresolved[].outcome，便于调用方按数据分支处理
• 空结果和分页提示会指出下一次调用内容，例如默认状态未找到结果时显示已关闭和已归档匹配项的数量，或关闭日期窗口为空时显示下一个截止日期
• 提供带有恢复提示的类型化失败原因，包括 Grants.gov 服务中断时的 upstream_unavailable、rate_limited 和 upstream_route_unavailable

开始使用

连接托管实例，无需安装：

claude mcp add --transport http grantsgov-mcp-server https://grantsgov.caseyjhand.com/mcp

或在本地运行：

claude mcp add grantsgov-mcp-server -- npx -y @cyanheads/grantsgov-mcp-server

对于其他客户端，将以下内容添加到 MCP 配置文件：

{
  "mcpServers": {
    "grantsgov-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/grantsgov-mcp-server"]
    }
  }
}

无需 API 密钥。有关 Docker 或从源代码构建，请参阅运行服务。

配置

此服务不读取自身的任何配置：Grants.gov API 无需密钥，且其端点固定。以下框架变量用于控制传输、身份验证和日志记录。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。服务声明为 stateless；仅在需要覆盖时设置此项。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+），并可访问网络连接至 api.grants.gov。

• 克隆并安装：

  git clone https://github.com/cyanheads/grantsgov-mcp-server.git
  cd grantsgov-mcp-server && bun install
  cp .env.example .env   # optional framework overrides
  

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/grantsgov-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/grantsgov-mcp-server。如需通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/grantsgov-mcp-server:latest"]。如需本地构建，请运行 docker build -t grantsgov-mcp-server .；默认会安装 OpenTelemetry 对等依赖项，构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和已发布的技能，并启动和释放 Grants.gov 服务。
src/mcp-server/tools/definitions	工具定义（*.tool.ts）。
src/mcp-server/tools	共享输入架构（input-schemas.ts）和 format() 渲染辅助函数（render.ts）。
src/services/grants-gov	Grants.gov API 客户端、关键词编译器、参考快照、日期和金额规范化、HTML 转文本。
tests/	与 src/ 目录结构对应的单元测试和工具测试，包含精简后的 Grants.gov 响应样例。
skills/	为审查联邦资助机会的 Agent 发布的指导内容。
docs/design.md	设计说明：探测到的 API 行为，以及工具接口设计背后的决策。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，并使用 ctx.fail 和工具声明的错误原因
• 在 src/mcp-server/tools/definitions/index.ts 中注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

数据来源

机会数据来自 Grants.gov，联邦机构会在此发布资助机会。这些记录属于美国政府作品。本项目与 Grants.gov 或任何联邦机构均无关联，也未获其认可。

许可证

本项目采用 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。