fcc-ecfs-mcp

An MCP server for the FCC's Electronic Comment Filing System (ECFS) public API. Implements every endpoint in ECFS's public OpenAPI spec — filings, a single filing, proceedings, a filing's documents, and non-docketed filing inboxes — plus an escape hatch for anything else. Lets an MCP client (Claude Desktop, Claude Code, etc.) search and fetch across all of them.

Tools

Related MCP server: mcp-fcc-ecfs

Setup

Option A: Claude Code plugin (recommended)

This repo is a Claude Code plugin — it bundles the MCP server and the slash commands below into a single install, and works from any directory (no manual config editing, no cd-ing into this repo first).

1. Get a free API key at https://www.fcc.gov/ecfs/help/public_api.

2. Install the plugin directly from this repo:

   /plugin install Reid-n0rc/fcc-ecfs-mcp

   Claude Code will prompt for your FCC ECFS API key (stored securely, not pasted into a config file) and an optional download folder for ecfs_download_document (default ~/Downloads/ecfs), and register both the fcc-ecfs MCP server and the /fcc-ecfs:* slash commands automatically.

3. To download documents, have Google Chrome installed.

Option B: Manual MCP server config

For non-Claude-Code MCP clients (Claude Desktop, etc.), or if you'd rather manage the server yourself:

1. Install dependencies and build:

   npm install
   npm run build

2. Provide the key via the ECFS_API_KEY environment variable — never commit it or pass it as a tool argument. For local development, copy .env.example to .env (git-ignored) and fill it in. The server reads .env from the root of this checkout, not from the client's working directory, and values in the client's env block always win. If you installed the server with npm or npx instead of cloning it, no .env is read: set everything in the client's env block.

3. Add to your client's MCP config:

   {
     "mcpServers": {
       "fcc-ecfs": {
         "command": "node",
         "args": ["/absolute/path/to/fcc-ecfs-mcp/dist/index.js"],
         "env": {
           "ECFS_API_KEY": "your-api-key-here",
           "ECFS_DOWNLOAD_DIR": "~/Downloads/ecfs"
         }
       }
     }
   }

   Prefer sourcing ECFS_API_KEY from your OS keychain or a secrets manager (e.g. 1Password, gpg-encrypted dotfiles) rather than pasting it into a config file where possible. ECFS_DOWNLOAD_DIR is optional (default ~/Downloads/ecfs).

Slash commands

commands/ ships Claude Code slash commands that wrap the tools above. Installed as a plugin, they're namespaced under fcc-ecfs:

Development

npm run dev        # run the server directly with tsx
npm test           # run the unit test suite (vitest)
npm run test:live  # run live tests against the real ECFS API (needs ECFS_API_KEY)
npm run test:download  # download a real document via headless Chrome (local only)
npm run typecheck  # type-check without emitting

CI (.github/workflows/ci.yml) runs the unit tests and the live tests on every push to main and every PR, plus weekly and on manual dispatch; docs-only changes skip the test jobs. Live tests use the ECFS_API_KEY secret (gh secret set ECFS_API_KEY, and again with --app dependabot for Dependabot PRs). Fork PRs can't read secrets, so they skip the live tests.

Changes to main go through a pull request that needs an approving review from the repo owner (.github/CODEOWNERS) and a passing ci-ok check, which rolls up every CI job. See CONTRIBUTING.md for the full workflow.

To test the plugin locally before publishing a change, rebuild and point Claude Code at the working tree:

npm run build
claude --plugin-dir .

Note that the plugin loader never runs npm run build on install — it only runs npm ci to fetch dependencies. dist/ must be committed and up to date before pushing.

Downloading documents

The ECFS public API is metadata-only: no endpoint returns a document's file bytes or text. A document's location (or a filing's documents[].src) points at https://www.fcc.gov/ecfs/document/{id_submission}/{n} on the ECFS website, which refuses non-browser HTTP clients such as curl with 403 Forbidden.

ecfs_download_document therefore opens that page in headless Google Chrome (via playwright-core, using your installed Chrome — no bundled browser download) and saves the PDF the page loads. Headless Chrome is presented under its regular Chrome user agent, since the site refuses the default HeadlessChrome one. No window is shown.

• Files are always saved inside ECFS_DOWNLOAD_DIR (plugin setting "Download folder"; default ~/Downloads/ecfs), named {id_submission}_{ECFS filename} and always with a .pdf extension. The model can put a file in a subfolder (output_dir, e.g. one per docket), but can't save outside the download folder. To save elsewhere, change the setting.

• Re-downloading an identical file reuses the existing copy; a different file with the same name gets a numeric suffix rather than overwriting.

• Each download takes a few seconds. The tool fetches one document per call; it isn't meant for bulk-downloading whole dockets.

Security notes

• The API key is read only from process.env.ECFS_API_KEY — it is never accepted as a tool input, so it cannot be echoed back into a model's context or transcript.

• Error messages and thrown errors redact the api_key query parameter before they are ever logged or returned to a client. Response bodies are also scrubbed of the literal key value before being returned — some ECFS response types (e.g. type=downloadplan) echo the key back verbatim in generated URLs, so URL-only redaction isn't sufficient.

• .env is git-ignored; only .env.example (no real key) is committed.

• The server never reads a .env from its working directory, only the checkout's own .env, so it can't pick up unrelated secrets from the project an MCP client was launched in. DOTENV_* variables don't affect it.

• ecfs_download_document only writes inside the download folder (ECFS_DOWNLOAD_DIR), checked both on the requested path and on its real path after resolving symlinks, and every saved file ends in .pdf. Tool arguments can be influenced by filing text the model has read, so the server doesn't trust output_dir to point anywhere else.

To report a vulnerability, see SECURITY.md.

License

MIT