fbi-crime-mcp-server

Public Hosted Server: https://fbi-crime.caseyjhand.com/mcp

Overview

US crime statistics from the FBI Crime Data Explorer: monthly offense rates and counts with population and reporting coverage at the national, state, or agency level, plus statistics on law enforcement officers killed and assaulted (LEOKA).

Tools

The nine unavailable entries above are disabled operator records, not callable tools. Visit FBI CDE for retired datasets.

Related MCP server: mcp-fbi-crime

Capability reference

fbi_get_crime_estimates tool

• scope: national (no identifiers), state (only state_abbr, two letters), or agency (only ori, nine letters/digits). Case is normalized to uppercase.

• offense: violent-crime, property-crime, robbery, burglary, larceny, motor-vehicle-theft, arson, aggravated-assault, rape, or homicide. Date range runs from_year/from_month through to_year/to_month (2000–2030; months default to January and December), and the start must not be later than the end.

• Returns entity_name, per-100k rates, actual/clearance counts, and nullable population, participated_population, and population_coverage_percent for each offense month, plus data_last_updated and max_data_date when the provider supplies them.

• Typed errors: scope_param_missing, scope_param_incompatible, invalid_date_range, no_data (also returned for a well-formed identifier the provider doesn't know).

fbi_get_leoka tool

• period: ytd (year-to-date; omit month) or monthly (requires month, 1–12); year is required (2000–2030)

• totals carries total_officers, total_incidents, total_officers_dod, total_officers_doi, total_incidents_dod, and total_incidents_doi from the CDE year-to-date block. It appears for both periods and is not a requested-month total. The upstream does not define dod/doi; they replace the removed total_*_felonious and total_*_accidental fields with the same values.

• Category-to-count maps: weapons, officer_activity, lighting_conditions, body_armor_worn, location_of_attack, offender_previously_known_to_agency, offender_prior_mental_illness, offender_prior_relationship, officer_circumstances_time_of_attack, officer_incident_type, officer_type_of_assignment, weather_conditions, offender_demographic, officer_demographic, officer_death_by_time_of_day, and officer_death_by_month.

• deaths_by_region and optional deaths_by_year break out killing types such as Felonious/Accidental; monthly responses omit the annual series. Absent sections are omitted, null counts mean unavailable, and zero stays zero.

• Typed errors: month_required (monthly period without month), month_not_applicable (YTD with month), no_data

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

• Nine retired tools retain disabled reasons on the HTTP landing page; MCP clients discover only the two callable tools and no resources

Agent-friendly output:

• Typed error reasons carry recovery hints for scope, date and period corrections, or unavailable data

• Sparse upstream rates, clearances, counts, populations and coverage surface as null rather than fabricated zeros

• data_last_updated and max_data_date echo the CDE's own dates

Getting started

Public Hosted Instance

A public instance is available at https://fbi-crime.caseyjhand.com/mcp — no installation required. No API key needed; the instance supplies its own. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "streamable-http",
      "url": "https://fbi-crime.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

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:

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

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 in the arrays passed to createApp() in src/index.ts

• Active tools call the CDE API (/cde/summarized/, /cde/leoka/); retired definitions are wrapped with disabledTool and omitted from MCP registration

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