CommonGrants Grant Seeker (MCP server)

An MCP server that searches grant opportunities across multiple CommonGrants-compliant APIs from a single set of tools. Ask an MCP client (Claude, ChatGPT, the MCP Inspector, …) to "find workforce development grants" and it fans out across every registered source and returns combined, labeled results.

Ships with three sources out of the box:

Because they all speak CommonGrants, the same tools work against any additional source you register.

Tools

All tools are read-only and carry the MCP annotations (readOnlyHint, openWorldHint) the Claude and OpenAI marketplaces require.

Related MCP server: grant-mcp

Quick start (local, stdio)

corepack enable
pnpm install

export FEDERAL_API_TOKEN="your-simpler-grants-key"   # optional; PA + CA are public
pnpm start

Then connect it to a client — see DEVELOPMENT.md for the Claude Desktop config and the MCP Inspector. A single-file, copy-paste demo also lives outside this repo for zero-setup demos.

Configuration

The default registry (federal/pa/ca) is defined in src/config/defaults.ts. To add your own sources or supply your own credentials, create a commongrants-mcp.config.ts in your working directory (or point CG_MCP_CONFIG at one):

import { defineConfig } from '@common-grants/mcp-grant-seeker/config';

export default defineConfig({
  sources: [
    { name: 'ca', label: 'California', baseUrl: 'https://ca.api.cg.a6lab.ai' },
    {
      name: 'my-foundation',
      label: 'My Foundation',
      baseUrl: 'https://grants.example.org',
      auth: { type: 'bearer', token: process.env.MY_FOUNDATION_TOKEN },
    },
  ],
});

See examples/commongrants-mcp.config.ts for the full annotated example.

Architecture

src/
├── core/          # transport- & host-agnostic: ICommonGrantsClient seam,
│   │              # SDK-backed client, tool registration, formatting
│   ├── client.ts  #   the ONLY file that touches @common-grants/sdk
│   ├── tools.ts   #   list_grant_sources / search_opportunities / get_opportunity
│   ├── server.ts  #   createServer(sources) → wired McpServer
│   └── format.ts
├── config/        # data-driven source registry (types, Zod schema,
│                  # defineConfig, defaults, jiti loader)
├── stdio.ts       # local entrypoint (Claude Desktop, Inspector, self-hosters)
└── worker.ts      # remote entrypoint — Cloudflare Workers (Phase 2 stub)

The server depends on an ICommonGrantsClient interface, not on the SDK directly, so SDK upgrades stay isolated to one file. Domain types are derived from the installed SDK so they never drift. See docs/adr/001-architecture.md.

Hosting & marketplaces

Both the Claude Connectors Directory and the OpenAI Apps SDK require a remote, HTTPS-hosted server; a single hosted URL is submitted to both. Because grant search is public, read-only data, the hosted server holds one server-side federal key and needs no per-user OAuth — users connect with zero config. The stdio server here is for local/self-hosted use. The remote Cloudflare Workers server is Phase 2 — see docs/adr/002-hosting-and-distribution.md.

Scripts

Contributing

See CONTRIBUTING.md and DEVELOPMENT.md. Licensed under MIT.