\n \n
\n\n**Ask your AI assistant real questions about U.S. federal regulations — and get answers grounded in the official Federal Register, eCFR, and regulations.gov.**\n\nThis is a [Model Context Protocol](https://modelcontextprotocol.io) server that connects any MCP client (Claude Desktop and others) to three official U.S. government sources:\n\n- **[Federal Register](https://www.federalregister.gov)** — the daily journal of the federal government: rules, proposed rules, notices, and presidential documents since 1994.\n- **[Electronic Code of Federal Regulations (eCFR)](https://www.ecfr.gov)** — the current, continuously updated text of the Code of Federal Regulations.\n- **[regulations.gov](https://www.regulations.gov)** — public comments, dockets, and live comment-period status for federal rulemakings.\n\nInstead of bolting on dozens of rigid, narrow tools, it hands the model a small, well-documented SDK and lets it write the exact query it needs in JavaScript — then runs that code in a locked-down sandbox. This is the **code-mode** pattern, and it makes wide government APIs usable without overwhelming the model with tool definitions.\n\n> Independent open-source project. It calls public U.S. government APIs and is not affiliated with or endorsed by the U.S. government.\n\n## See it in action\n\nAsk Claude:\n\n> *\"What does 50 CFR 21.150 cover, and have there been recent Federal Register rules touching migratory-bird depredation?\"*\n\nThe model finds the right calls and runs them in the sandbox — no hand-written tool per endpoint:\n\n```ts\n// Pull the current text of an eCFR section…\nconst { titles } = await ecfr.titles.list();\nconst date = titles.find(t => t.number === 50).latest_issue_date;\nconst section = await ecfr.full(date, 50, { part: '21', section: '21.150' });\n\n// …and search the Federal Register for related rulemaking.\nconst rules = await fr.documents.search({\n conditions: { term: 'migratory bird depredation', type: ['RULE', 'PRORULE'] },\n fields: ['title', 'publication_date', 'html_url'],\n per_page: 5,\n order: 'newest',\n});\n```\n\n…then answers in plain English, citing the section and the rules it found.\n\n## Features\n\n- **Three official sources, one server** — the full Federal Register v1 (`fr.*`), eCFR (`ecfr.*`), and regulations.gov v4 (`regs.*`) APIs behind one server.\n- **Code mode, not tool sprawl** — the model writes JavaScript against the `fr` / `ecfr` / `regs` SDKs instead of juggling dozens of single-purpose tools.\n- **Safe by construction** — user code runs in an `isolated-vm` (or Deno) sandbox with **no network, filesystem, env, or subprocess access**. The only way out is to the three upstream government APIs.\n- **Runs anywhere MCP does** — stdio for Claude Desktop, or a remote Streamable HTTP server with OAuth, rate limiting, and quotas.\n- **Discovery built in** — `search_api` and `describe_schema` help the model (and you) find the right call fast.\n\n## Which source for what\n\n| Need | Source |\n|---|---|\n| Daily rules, proposed rules, notices; FR document metadata since 1994 | `fr` |\n| Current Code of Federal Regulations text | `ecfr` |\n| Public comments, dockets, live comment-period status | `regs` |\n\nFor canonical Federal Register rule text and metadata since 1994, prefer `fr.documents` — regulations.gov documents overlap it. Reach for `regs` when you need what only it has: public **comments**, **dockets**, and live comment-period status.\n\n### regulations.gov API key\n\nregulations.gov requires a free API key from [api.data.gov / open.gsa.gov](https://open.gsa.gov/api/regulationsgov/). Set it via `FEDREG_REGS_API_KEY`. The key is held host-side and never reaches the sandbox.\n\nWithout a key the `regs` source is **disabled** — `regs.*` calls return a clear `SourceUnavailable` error, while `fr` and `ecfr` keep working normally.\n\nBecause the regulations.gov key is shared, `regs` upstream calls are bounded by a process-wide hourly bucket (`FEDREG_REGS_RATE_PER_HOUR`), a per-subject hourly quota in HTTP mode (`FEDREG_REGS_SUBJECT_RATE_PER_HOUR`; under `--insecure` all callers share the single `anonymous` bucket, and stdio skips it), and a per-`execute()` call budget (`FEDREG_REGS_MAX_CALLS_PER_EXECUTE`). For the two hourly rates, `0` is **not** \"unlimited\" — it blocks all regs calls; to disable regs entirely, leave `FEDREG_REGS_API_KEY` unset.\n\n### Bridge example: comments on a Federal Register rule\n\n`frDocNum` is a *returned* attribute on regs documents, not a filter — so bridge from FR to regulations.gov via the document number as a `searchTerm`:\n\n```ts\n// 1. Find the rule in the Federal Register and read its document number.\nconst fr1 = await fr.documents.search({\n conditions: { term: 'methane', type: ['RULE'] },\n per_page: 1,\n order: 'newest',\n});\nconst docNum = fr1.results[0].document_number;\n\n// 2. Look it up on regulations.gov by document number, then read its objectId.\nconst rd = await regs.documents.search({ filter: { searchTerm: docNum } });\nconst objectId = rd.data[0].attributes.objectId;\n\n// 3. Pull the public comments filed on that document.\nconst comments = await regs.comments.search({\n filter: { commentOnId: objectId },\n page: { size: 250 },\n});\n```\n\n## Quickstart (Claude Desktop)\n\nAdd the server to your Claude Desktop config (**Settings → Developer → Edit Config**):\n\n```json\n{\n \"mcpServers\": {\n \"fedreg\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@blen/fedreg-mcp-server\"]\n }\n }\n}\n```\n\nRestart Claude Desktop, then just ask in plain language:\n\n> *\"Find EPA methane rules published since 2024.\"*\n> *\"What does 40 CFR Part 60 cover?\"*\n> *\"Which proposed rules opened for public comment this week?\"*\n\nRequires **Node.js ≥ 20.10**. `npx` downloads and runs the server on demand; no global install needed. If the `execute` tool reports `SandboxUnavailable`, see [Sandbox runtimes](#sandbox-runtimes).\n\n## How it works\n\nThree tools, in the order the model uses them:\n\n| Tool | What it does |\n|---|---|\n| `search_api(query, k?)` | Finds the right endpoint/field via BM25 over the SDK docs. Returns signatures and ready-to-run JavaScript snippets. |\n| `describe_schema({ path? \\| prefix? })` | Looks up an exact call or lists a whole namespace. |\n| `execute({ code, timeoutMs?, memoryMb? })` | Runs JavaScript (no type annotations; top-level `await`/`return` allowed) in the sandbox, with `fr`, `ecfr`, and `regs` as globals. (`regs` is always defined; without `FEDREG_REGS_API_KEY` its calls return a `SourceUnavailable` error rather than a `ReferenceError`.) |\n\nAll three tools carry MCP annotations marking them read-only and non-destructive (`execute` is additionally `openWorldHint: true`, since it reaches the upstream APIs), so clients that honor annotations can auto-approve them.\n\nA request flows from the MCP client through `execute` into the sandbox; the `fr.*` / `ecfr.*` / `regs.*` globals are thin proxies that marshal each call across a host-side RPC bridge to the real APIs:\n\n```text\nMCP client → execute(code) → sandbox → fr.* / ecfr.* / regs.* RPC bridge → upstream APIs\n```\n\nFull SDK surface: [`docs/sdk-reference.md`](./docs/sdk-reference.md) · Architecture: [`docs/architecture.md`](./docs/architecture.md) · Paste-ready examples: [`examples/`](./examples/).\n\n## Sandbox runtimes\n\n`execute` needs a sandbox runner. The server picks one automatically:\n\n1. **`isolated-vm`** (preferred) — a fresh V8 isolate. Built automatically during install on Linux/macOS/Windows (x64/arm64) where a C++ toolchain is present.\n2. **Deno** (fallback) — used when `isolated-vm` isn't available and `deno` is on `PATH`.\n3. If neither is available, `search_api` and `describe_schema` still work; `execute` returns `SandboxUnavailable`.\n\n> On very new Node majors, `isolated-vm` may not have a compatible prebuild yet. Install [Deno](https://docs.deno.com/runtime/getting_started/installation/) and run with `--sandbox deno` (or `FEDREG_SANDBOX=deno`). Node 20 and 22 build `isolated-vm` cleanly.\n\n## Self-hosting (remote HTTP)\n\nRun a shared, authenticated endpoint over Streamable HTTP:\n\n```bash\n# Dev only — no auth, loopback-bound:\nnpx @blen/fedreg-mcp-server --http --insecure --host 127.0.0.1 --port 8080\n\n# Production — auth via any OIDC issuer:\nFEDREG_AUTH_PROVIDER=clerk \\\nFEDREG_AUTH_ISSUER=https://