io.github.cyanheads/fbi-crime-mcp-server

---

Overview

FBI Crime Data Explorer (CDE) data — monthly UCR offense rates and counts by national, state, or agency scope, plus Law Enforcement Officers Killed and Assaulted (LEOKA) statistics. Query crime trends and officer-safety data from any MCP client; the CDE's legacy UCR endpoints (agency search, NIBRS breakdowns, hate crimes, arrests, human trafficking, participation) have been decommissioned by the FBI, and their tools and resources return an error. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
fbi_get_crime_estimates	Monthly UCR offense rates and counts by national, state, or agency scope, from the CDE summarized endpoint
fbi_get_agency_offenses	Same CDE summarized endpoint, scoped to a single agency, state, or the national level
fbi_get_leoka	Officer fatality, weapon, and circumstance data (LEOKA) by month or year-to-date
fbi_get_arson	[UNAVAILABLE] Redirects to fbi_get_crime_estimates with offense="arson"
fbi_search_agencies	[UNAVAILABLE] UCR agency search backend decommissioned
fbi_get_agency	[UNAVAILABLE] UCR agency profile backend decommissioned
fbi_get_arrests	[UNAVAILABLE] UCR arrests backend decommissioned
fbi_get_hate_crimes	[UNAVAILABLE] UCR hate crimes backend decommissioned
fbi_get_human_trafficking	[UNAVAILABLE] UCR human trafficking backend decommissioned
fbi_get_nibrs_breakdown	[UNAVAILABLE] UCR NIBRS breakdown backend decommissioned
fbi_get_participation	[UNAVAILABLE] UCR and CDE participation backends decommissioned
fbi_list_code_table	[UNAVAILABLE] UCR code table backend decommissioned

Resources

Resource	Description
fbi://agency/{ori}	[UNAVAILABLE] Agency profile by ORI; UCR backend decommissioned
fbi://state/{state_abbr}	[UNAVAILABLE] State participation overview; CDE backend decommissioned

Capability reference

fbi_get_crime_estimates _tool

• scope: national, state (requires state_abbr, 2 letters), or agency (requires ori, 9 characters)
• offense: one of violent-crime, property-crime, robbery, burglary, larceny, motor-vehicle-theft, arson, aggravated-assault, rape, homicide
• Date range via from_year/from_month (default January) and to_year/to_month (default December), years 2000–2030
• Returns per-100k rates and raw actual/clearance counts by month, plus data_last_updated when the CDE reports a refresh date
• Typed errors: scope_param_missing (missing state_abbr/ori for the chosen scope), no_data

---

fbi_get_agency_offenses _tool

• Same CDE summarized endpoint as fbi_get_crime_estimates, scoped by scope: national, state (state_abbr), or agency (ori)
• Same offense enum and from_year/from_month/to_year/to_month range (years 2000–2030)
• Typed errors: scope_param_missing, no_data

---

fbi_get_leoka _tool

• period: ytd (year-to-date) or monthly (requires month, 1–12); year is required (2000–2030)
• Returns fatality totals (feloniously/accidentally killed, incident counts), plus weapon, officer-activity, lighting-condition, and geographic-region breakdowns when the CDE reports them
• deaths_by_year and deaths_by_region are keyed by Felonious/Accidental
• Typed errors: month_required (monthly period without month), no_data

---

fbi_get_arson _tool

• Always throws ServiceUnavailable — the dedicated UCR arson endpoint is decommissioned
• Recovery hint redirects to fbi_get_crime_estimates with offense="arson", which serves arson data via the CDE summarized endpoint
• Input fields (scope, state_abbr, since_year, until_year) are accepted but unused

---

fbi_search_agencies _tool

• Always throws ServiceUnavailable — the UCR agency search backend (crime-data-api.fr.cloud.gov) is decommissioned
• Recovery hint points to cde.ucr.cjis.gov or the FBI UCR program
• Input fields (state_abbr, agency_type, city, population_group, page, per_page) are accepted but unused

---

fbi_get_agency _tool

• Always throws ServiceUnavailable — the UCR agency profile backend is decommissioned, with no CDE replacement identified
• Recovery hint points to cde.ucr.cjis.gov
• ori input is accepted but unused

---

fbi_get_arrests _tool

• Always throws ServiceUnavailable — the UCR arrests backend is decommissioned
• Recovery hint points to cde.ucr.cjis.gov or FBI bulk CSV downloads
• since_year/until_year inputs are accepted but unused

---

fbi_get_hate_crimes _tool

• Always throws ServiceUnavailable — the UCR hate crimes backend is decommissioned
• Recovery hint points to cde.ucr.cjis.gov
• Input fields (scope, state_abbr, since_year, until_year, cross_offense) are accepted but unused

---

fbi_get_human_trafficking _tool

• Always throws ServiceUnavailable — the UCR human trafficking backend is decommissioned
• Recovery hint points to cde.ucr.cjis.gov
• Input fields (scope, state_abbr, ori, since_year, until_year) are accepted but unused

---

fbi_get_nibrs_breakdown _tool

• Always throws ServiceUnavailable — the UCR NIBRS breakdown backend is decommissioned
• Recovery hint points to cde.ucr.cjis.gov
• Input fields (dimension, variable, scope, state_abbr, offense_name, since_year, until_year) are accepted but unused

---

fbi_get_participation _tool

• Always throws ServiceUnavailable — both the UCR legacy backend and the CDE /LATEST/participation/ path are decommissioned (404)
• Recovery hint points to cde.ucr.cjis.gov
• Input fields (scope, state_abbr, year, nibrs_only, page, per_page) are accepted but unused

---

fbi_list_code_table _tool

• Always throws ServiceUnavailable — the UCR code table backend is decommissioned
• Recovery hint points to cde.ucr.cjis.gov
• table input (one of 10 code-table names) is accepted but unused

---

fbi://agency/{ori} _resource

• Always throws ServiceUnavailable on read — the UCR agency profile backend is decommissioned
• ori is the 9-character ORI (Originating Agency Identifier) code

---

fbi://state/{state_abbr} _resource

• Always throws ServiceUnavailable on read — the CDE /LATEST/participation/state/ path returns 404
• state_abbr is the two-letter US state abbreviation

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

FBI CDE-specific:

• CDE summarized endpoint (/cde/summarized/) for national, state, and per-agency offense rates and counts across 10 offense types
• CDE LEOKA endpoint (/cde/leoka/) for officer fatality, weapon, and circumstance data by month or year-to-date
• DEMO_KEY works without registration (shared, rate-limited pool); a registered api.data.gov key raises throughput
• 9 of 12 tools and both resources return a ServiceUnavailable error — the legacy UCR backend (crime-data-api.fr.cloud.gov) was decommissioned; fbi_get_arson redirects callers to fbi_get_crime_estimates

Agent-friendly output:

• Typed error reasons (scope_param_missing, no_data, month_required, endpoint_decommissioned) each carry a recovery hint naming the next step or the cde.ucr.cjis.gov replacement
• Sparse upstream fields surface as null rather than fabricated zeros, on the rate, clearance, and count fields of fbi_get_crime_estimates and fbi_get_agency_offenses
• data_last_updated echoes the CDE's own refresh timestamp so agents can reason about freshness

Getting started

Add the following to your MCP client configuration file. See the FBI CDE API key registration to obtain a key — DEMO_KEY works for exploration but is rate-limited.

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fbi-crime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FBI_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/fbi-crime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FBI_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "FBI_API_KEY=your-api-key",
        "ghcr.io/cyanheads/fbi-crime-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 FBI_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• An api.data.gov API key for the FBI CDE API. DEMO_KEY works for testing but is rate-limited to ~1,000 req/hr from a shared pool.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/fbi-crime-mcp-server.git

2. Navigate into the directory:

cd fbi-crime-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env and set FBI_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
FBI_API_KEY	Required. api.data.gov API key for the FBI CDE API. Use DEMO_KEY for limited testing.	—
FBI_API_BASE_UCR	Override UCR base URL.	https://api.usa.gov/crime/fbi/ucr
FBI_API_BASE_CDE	Override CDE base URL.	https://api.usa.gov/crime/fbi/cde
FBI_REQUEST_TIMEOUT_MS	Per-request timeout in milliseconds.	15000
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path.	/mcp
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto (resolves to stateful). The server declares stateless in code; set this to override it.	stateless
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments.	none
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
MCP_GC_PRESSURE_INTERVAL_MS	Opt-in Bun-only forced-GC pressure interval (ms). Try 60000 if RSS grows under sustained HTTP load.	0
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.	in-memory
OTEL_ENABLED	Enable OpenTelemetry instrumentation.	false

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

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

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t fbi-crime-mcp-server .
docker run --rm -e FBI_API_KEY=your-key -p 3010:3010 fbi-crime-mcp-server

The 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.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools, resources, and inits services.
src/config	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools	Tool definitions (*.tool.ts). 12 tools — 3 active via CDE API, 9 decommissioned.
src/mcp-server/resources	Resource definitions (*.resource.ts). Agency and state overview resources.
src/services	FBI API service layer — UCR and CDE clients with shared retry/timeout logic.
tests/	Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
• Active tools call the CDE API (/cde/summarized/, /cde/leoka/); decommissioned tools throw serviceUnavailable with a recovery hint
• Wrap FBI API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.