fbi-crime-mcp-server
by cyanheads
README.md
<div align="center">
<h1>@cyanheads/fbi-crime-mcp-server</h1>
<p><b>Exposes the FBI Crime Data Explorer API — monthly UCR offense rates and counts by national, state, or agency scope, plus LEOKA officer-safety statistics via MCP. STDIO or Streamable HTTP.</b>
<div>2 Callable Tools • 9 Disabled Tools • 0 Registered Resources</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/fbi-crime-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/fbi-crime-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](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)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://fbi-crime.caseyjhand.com/mcp](https://fbi-crime.caseyjhand.com/mcp)
</div>
---
## 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
| 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_leoka` | Officer fatality, weapon, and circumstance data (LEOKA) by month or year-to-date |
| `fbi_get_arson` | [DISABLED] Use `fbi_get_crime_estimates` with `offense="arson"` |
| `fbi_search_agencies` | [DISABLED] UCR agency search backend decommissioned |
| `fbi_get_agency` | [DISABLED] UCR agency profile backend decommissioned |
| `fbi_get_arrests` | [DISABLED] UCR arrests backend decommissioned |
| `fbi_get_hate_crimes` | [DISABLED] UCR hate crimes backend decommissioned |
| `fbi_get_human_trafficking` | [DISABLED] UCR human trafficking backend decommissioned |
| `fbi_get_nibrs_breakdown` | [DISABLED] UCR NIBRS breakdown backend decommissioned |
| `fbi_get_participation` | [DISABLED] UCR and CDE participation backends decommissioned |
| `fbi_list_code_table` | [DISABLED] UCR code table backend decommissioned |
The nine unavailable entries above are disabled operator records, not callable tools. Visit [FBI CDE](https://cde.ucr.cjis.gov/) for retired datasets.
## Capability reference
### `fbi_get_crime_estimates` <sub>tool</sub>
- `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` <sub>tool</sub>
- `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`](https://github.com/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:
```json
{
"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](https://api.data.gov/signup/) to obtain a key — DEMO_KEY works for exploration but is rate-limited.
```json
{
"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):
```json
{
"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:
```json
{
"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:
```sh
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](https://bun.sh/) or higher (or Node.js v24+).
- 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.
### Installation
1. **Clone the repository:**
```sh
git clone https://github.com/cyanheads/fbi-crime-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd fbi-crime-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
4. **Configure environment:**
```sh
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](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP base URL for trace and metric export; does not enable log export. | none |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Explicit OTLP log export endpoint; the Docker image includes the required optional peers. | none |
See [`.env.example`](./.env.example) for the full list of optional overrides.
## Running the server
### Local development
- **Build and run:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions against spec
```
### Docker
```sh
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`). 2 callable tools and 9 disabled operator entries. |
| `src/mcp-server/resources` | Retired agency/state definitions, not registered. |
| `src/services` | FBI CDE API service with response validation and shared retry/timeout logic. |
| `tests/` | Unit and integration tests mirroring `src/`. |
## Development guide
See [`CLAUDE.md`](./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:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](./LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessResponsive