Exposes the FBI Crime Data Explorer API — UCR crime estimates, NIBRS incident breakdowns, hate crimes, arrests, human trafficking, and agency participation data via MCP. STDIO or Streamable HTTP.\n
12 Tools (4 active via CDE API, 8 decommissioned) • 2 Resources
\n\n[](https://github.com/cyanheads/fbi-crime-mcp-server/releases/latest/download/fbi-crime-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=fbi-crime-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZmJpLWNyaW1lLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7IkZCSV9BUElfS0VZIjoieW91ci1hcGkta2V5In19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22fbi-crime-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ffbi-crime-mcp-server%22%5D%2C%22env%22%3A%7B%22FBI_API_KEY%22%3A%22your-api-key%22%7D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\n12 tools defined. **4 are active** via the FBI CDE API; **8 are decommissioned** — the legacy UCR backend (`crime-data-api.fr.cloud.gov`) was shut down, and those tools return a `ServiceUnavailable` error on every call with guidance to the FBI CDE website.\n\n### Active tools (CDE API)\n\n| Tool | Description |\n|:-----|:------------|\n| `fbi_get_crime_estimates` | Monthly offense rates (per 100k) and raw counts from the FBI CDE summarized endpoint. National, state, or agency scope. Covers violent-crime, property-crime, robbery, burglary, larceny, motor-vehicle-theft, arson, aggravated-assault, rape, homicide. |\n| `fbi_get_agency_offenses` | Same CDE summarized endpoint, scoped to a single agency by ORI code. Returns month-by-month rates and counts for that agency. |\n| `fbi_get_leoka` | Law Enforcement Officers Killed and Assaulted (LEOKA) — fatality and assault counts with circumstance and weapon detail, by month or year-to-date. |\n| `fbi_get_arson` | Redirects to `fbi_get_crime_estimates` with `offense=\"arson\"` — arson data is available via the CDE summarized endpoint. |\n\n### Decommissioned tools (always return error)\n\n| Tool | Status |\n|:-----|:-------|\n| `fbi_search_agencies` | UCR agency search backend decommissioned |\n| `fbi_get_agency` | UCR agency lookup backend decommissioned |\n| `fbi_get_arrests` | UCR arrests backend decommissioned |\n| `fbi_get_hate_crimes` | UCR hate crimes backend decommissioned |\n| `fbi_get_participation` | UCR participation backend decommissioned |\n| `fbi_get_human_trafficking` | UCR human trafficking backend decommissioned |\n| `fbi_get_nibrs_breakdown` | NIBRS backend decommissioned |\n| `fbi_list_code_table` | UCR code table backend decommissioned |\n\nFor decommissioned data, consult [cde.ucr.cjis.gov](https://cde.ucr.cjis.gov/) or download FBI bulk CSV files.\n\n### `fbi_get_crime_estimates`\n\nMonthly offense rates and raw counts from the FBI CDE summarized endpoint.\n\n- Scope: `national`, `state` (requires `state_abbr`), or `agency` (requires ORI)\n- Offense types: `violent-crime`, `property-crime`, `robbery`, `burglary`, `larceny`, `motor-vehicle-theft`, `arson`, `aggravated-assault`, `rape`, `homicide`\n- Returns per-100k rates and raw actuals by month for the requested date range\n\n---\n\n### `fbi_get_agency_offenses`\n\nSame CDE summarized endpoint scoped to a single agency, state, or national level.\n\n- Functionally equivalent to `fbi_get_crime_estimates` with `scope=\"agency\"` — useful when the agent's mental model is \"offenses for this agency\" rather than \"crime trends\"\n- Provide ORI for agency scope; `state_abbr` for state scope\n\n---\n\n### `fbi_get_leoka`\n\nLaw Enforcement Officers Killed and Assaulted (LEOKA) data.\n\n- Two period modes: `monthly` (by month) or `ytd` (year-to-date)\n- Returns feloniously killed, accidentally killed, and assault counts with circumstance and weapon detail\n\n---\n\n### `fbi_get_arson`\n\nRedirects to `fbi_get_crime_estimates` with `offense=\"arson\"`. The dedicated UCR arson endpoint is decommissioned; arson data remains available via the CDE summarized endpoint.\n\n## Resources\n\n| Type | Name | Description |\n|:-----|:-----|:------------|\n| Resource | `fbi://agency/{ori}` | [UNAVAILABLE] The UCR agency profile backend has been decommissioned; reading this resource returns a `ServiceUnavailable` error. |\n| Resource | `fbi://state/{state_abbr}` | [UNAVAILABLE] The CDE state participation backend has been decommissioned; reading this resource returns a `ServiceUnavailable` error. |\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool and resource definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nFBI Crime Data Explorer-specific:\n\n- **CDE API** (`/cde/summarized/`, `/cde/leoka/`) — the surviving FBI endpoints post-UCR decommission\n- Decommissioned tools return a `ServiceUnavailable` error with a recovery hint pointing to [cde.ucr.cjis.gov](https://cde.ucr.cjis.gov/) — agents can report the gap rather than silently failing\n- `DEMO_KEY` works without signing up (rate-limited shared pool); a registered api.data.gov key for production throughput\n\n## Getting started\n\nAdd the following to your MCP client configuration file. See the [FBI CDE API key registration](https://api.data.gov/signup/) to obtain a key — DEMO_KEY works for exploration but is rate-limited.\n\n```json\n{\n \"mcpServers\": {\n \"fbi-crime-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/fbi-crime-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"FBI_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"fbi-crime-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/fbi-crime-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\",\n \"FBI_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"fbi-crime-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"-e\", \"FBI_API_KEY=your-api-key\",\n \"ghcr.io/cyanheads/fbi-crime-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 FBI_API_KEY=... bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.2](https://bun.sh/) or higher (or Node.js v24+).\n- An [api.data.gov API key](https://api.data.gov/signup/) for the FBI CDE API. `DEMO_KEY` works for testing but is rate-limited to ~1,000 req/hr from a shared pool.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/fbi-crime-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd fbi-crime-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env and set FBI_API_KEY\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `FBI_API_KEY` | **Required.** api.data.gov API key for the FBI CDE API. Use `DEMO_KEY` for limited testing. | — |\n| `FBI_API_BASE_UCR` | Override UCR base URL. | `https://api.usa.gov/crime/fbi/ucr` |\n| `FBI_API_BASE_CDE` | Override CDE base URL. | `https://api.usa.gov/crime/fbi/cde` |\n| `FBI_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds. | `15000` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path. | `/mcp` |\n| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments. | none |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |\n| `MCP_GC_PRESSURE_INTERVAL_MS` | Opt-in Bun-only forced-GC pressure interval (ms). Try `60000` if RSS grows under sustained HTTP load. | `0` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t fbi-crime-mcp-server .\ndocker run --rm -e FBI_API_KEY=your-key -p 3010:3010 fbi-crime-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/fbi-crime-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools, resources, and inits services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). 12 tools — 4 active via CDE API, 8 decommissioned. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Agency and state overview resources. |\n| `src/services` | FBI API service layer — UCR and CDE clients with shared retry/timeout logic. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`\n- Active tools call the CDE API (`/cde/summarized/`, `/cde/leoka/`); decommissioned tools throw `serviceUnavailable` with a recovery hint\n- Wrap FBI API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](./LICENSE) for details.\n",
"bytes": 12703,
"sha": "9855764a78c51d6fa5bc92c02bc1e9e852b572b12816ccdc03967c67a392bd63",
"repo_slug": "cyanheads/fbi-crime-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_fbi_crime_mcp_server_d0294c1e/readme"
}