FastBound MCP Server
xuanji86/fastbound-mcp
Integração MCP com FastBound A&D para gerenciamento de inventário regulado de armas
Ver no GitHubServidor MCP para integração com a API FastBound de Aquisição & Disposição de armas de fogo (A&D), utilizada por licenciados federais (FFLs) nos EUA. Fornece 51 ferramentas para buscar inventário, registrar aquisições/disposições, gerenciar contatos e gerar relatórios através de linguagem natural, com modelo de segurança de gravação protegida e dry-run.
Instalação
npx convez-ai xuanji86/fastbound-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Busca e consulta de inventário de armas e munições via linguagem natural
- Registro seguro de aquisições e disposições com validação prévia (dry-run)
- Geração de relatórios e consultas sobre transações de armas para FFLs
- Gerenciamento de contatos e webhooks integrados ao FastBound
Veredito

Integração robusta e bem-arquitetada para o ecossistema FastBound com forte ênfase em segurança regulatória (desabilitação padrão de gravações, dry-run obrigatório, conformidade ATF). Essencial para FFLs que utilizam Claude, mas restrito a nicho específico de usuários com conta FastBound.
README
A tradução para o português deste README ainda está na fila.
FastBound MCP
An MCP server for the FastBound firearms Acquisition & Disposition (A&D) API — the electronic bound book used by US Federal Firearms Licensees (FFLs). It lets an MCP client (Claude Desktop, Claude Code, Codex CLI, Codex Desktop, etc.) search inventory, record acquisitions and dispositions, manage contacts, and pull reports through natural language.
⚠️ Compliance disclaimer. This tool writes to ATF-regulated records (27 CFR Part 478). You — the FFL/operator — are solely responsible for the accuracy and legality of every record. Test against a FastBound TEST account before touching production data. Writes are disabled by default (see Write safety).
Unofficial. A community-built integration — not affiliated with, endorsed by, or sponsored by FastBound. "FastBound" is a trademark of its respective owner, used here nominatively to describe API compatibility. See
NOTICE.
Features
- 51 tools covering account/reference, items, acquisitions, dispositions, contacts, reports, webhooks, and inventory — comprehensive coverage of the FastBound v1 Account API.
- Guarded writes with dry-run preview. Writes are off unless you opt in; committing/destructive operations preview exactly what they will send and require an explicit
confirm:true. - Rate-limit aware (60 req/min token bucket + 429 backoff) and surfaces FastBound's side-effect headers (multiple-sale reports, auto-acquisitions on FFL transfers, contact dedupe).
Install
The server runs over stdio and is configured entirely through environment variables.
Claude Code
claude mcp add fastbound \
-e FASTBOUND_ACCOUNT_NUMBER=12345 \
-e FASTBOUND_API_KEY=your-api-key \
-e FASTBOUND_AUDIT_USER=you@ffl.com \
-e FASTBOUND_ALLOW_WRITES=false \
-- npx -y fastbound-mcp
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"fastbound": {
"command": "npx",
"args": ["-y", "fastbound-mcp"],
"env": {
"FASTBOUND_ACCOUNT_NUMBER": "12345",
"FASTBOUND_API_KEY": "your-api-key",
"FASTBOUND_AUDIT_USER": "you@ffl.com",
"FASTBOUND_ALLOW_WRITES": "false"
}
}
}
}
Codex (CLI & Desktop)
Codex loads MCP servers over stdio, and both the Codex CLI and the Codex desktop / IDE app read the same config file: ~/.codex/config.toml. This is a standard stdio MCP server, so a single entry works for both:
[mcp_servers.fastbound]
command = "node"
args = ["/absolute/path/to/fastbound-mcp/dist/index.js"]
env = { FASTBOUND_ACCOUNT_NUMBER = "12345", FASTBOUND_API_KEY = "your-api-key", FASTBOUND_AUDIT_USER = "you@ffl.com", FASTBOUND_ALLOW_WRITES = "false" }
- Codex CLI — run
npm run buildfirst sodist/exists, then startcodex; the/mcpcommand lists the connectedfastboundserver and its tools. - Codex Desktop / IDE extension — shares the same
~/.codex/config.toml. Add the block above (or use the app's MCP settings panel), then restart the app to load it.
If you npm i -g . (or publish the package), replace the node + absolute-path form with command = "fastbound-mcp".
Compatibility is verified end-to-end: all 51 tool schemas are standard JSON Schema (draft-07, additionalProperties: false, no $ref/anyOf); tool names stay within OpenAI's function-name limits; the server emits only clean newline-delimited JSON-RPC on stdout (no log pollution) and negotiates MCP protocol 2025-06-18. Codex's client accepts the tools without modification.
Configuration
| Variable | Required | Default | Purpose |
|---|---|---|---|
FASTBOUND_ACCOUNT_NUMBER | yes | — | Account number (the numeric id in your cloud.fastbound.com URL). Used as the Basic-auth username. |
FASTBOUND_API_KEY | yes | — | API key from Settings → Account. Basic-auth password. |
FASTBOUND_AUDIT_USER | recommended | — | Email recorded as X-AuditUser on writes (ATF audit trail). Must be an active account user. Per-call auditUser overrides it. |
FASTBOUND_ALLOW_WRITES | no | false | Master write switch. When false, every write tool refuses and sends nothing. |
FASTBOUND_BASE_URL | no | https://cloud.fastbound.com | API root override. |
FASTBOUND_API_VERSION | no | — | Optional x-api-version header. |
Get a free TEST account at fastbound.com to build and validate integrations without affecting real records. Generate the API key in Settings → Account, and find the account number in your dashboard URL.
Write safety
This server treats writes as dangerous by default:
- Off by default. With
FASTBOUND_ALLOW_WRITESunset/false, every write tool returnsBLOCKEDand sends nothing. - Audit user required. Writes need a valid
X-AuditUseremail (fromFASTBOUND_AUDIT_USERor a per-callauditUser). - Dry-run by default for the dangerous ones. Committing or destructive tools (
acquire,dispose,commit_*,delete_item,undispose_item,merge_contacts,update_*, theft-loss/destroyed/NFA, …) return aDRY RUNpreview showing the exact method, path, and request body. Re-call withconfirm:trueto execute. The preview is built from the same code that sends the live request, so it can't drift. - Staging tools execute directly. Creating pending (uncommitted) records or adding items to them carries no ATF effect, so those run without a confirm step (but still require the write switch + audit user).
Tool results are tagged OK / DRY RUN / BLOCKED / ERROR on the first line.
Tools
- Reference:
get_account,list_smartlists,list_users - Items:
search_items,get_item,update_item,set_item_external_id,set_item_acquisition_contact,delete_item,undispose_item - Acquisitions:
search_acquisitions,get_acquisition,get_acquisition_item,acquire,create_pending_acquisition,add_acquisition_items,update_acquisition,update_acquisition_item,attach_acquisition_contact,commit_acquisition,delete_acquisition,delete_acquisition_item - Dispositions:
search_dispositions,get_disposition,list_disposition_items,list_4473_dispositions,dispose,create_pending_disposition,add_disposition_items,update_disposition,edit_disposition_item_price,attach_disposition_contact,remove_disposition_items,commit_disposition,lock_disposition,dispose_theft_loss,dispose_destroyed,dispose_nfa,delete_disposition - Contacts:
search_contacts,get_contact,create_contact,update_contact,manage_contact_licenses,merge_contacts - Reports:
download_bound_book,download_4473,download_attachment,download_multiple_sale_report - Webhooks / Inventory:
manage_webhooks,bulk_verify_inventory
Firearm classification fields (caliber, manufacturer, type, condition, location) are account-configurable — use list_smartlists to discover valid values before writing.
Development
npm install
npm run build # tsc → dist/
npm test # vitest (offline unit tests)
npm run typecheck
The unit tests are fully mocked and offline. An opt-in live smoke test (test/smoke.account.test.ts) runs read-only get_account against a real account when FASTBOUND_ACCOUNT_NUMBER/FASTBOUND_API_KEY are set, and skips otherwise:
FASTBOUND_ACCOUNT_NUMBER=... FASTBOUND_API_KEY=... npx vitest run test/smoke.account.test.ts
License
MIT