# Footgun [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/GetFootgun/footgun  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1069  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/footgun

## Description
Dated, verified fixes for how APIs and AI coding tools break, served to your agent before it codes.

## Tools
Capabilities this server exposes over MCP:

- **lookup_traps** — Call before writing code against a third-party API, platform, or AI tool. Returns up to 10 verified, dated failure modes for that provider, each with symptoms, cause, fix, a code example and the date it was last checked. Use search_traps instead when you already have an error message.
- **search_traps** — Call when a call to a third-party service fails or behaves unexpectedly. Paste the error text. Returns up to 5 verified traps whose symptoms match it, closest first, each with cause and fix. Returns nothing when no trap matches closely. Use lookup_traps instead before writing code.
- **file_trap** — Draft a trap after a failure was fixed. Private by default with a Pro or Team key. Public filings are checked automatically against official sources and published only when an official source confirms them. A reviewer can still act on any filing. Citing the provider's official documentation or changelog in sources helps. No API key needed. Set visibility to public to submit to the public registry.
- **confirm_trap** — After you hit or avoid a trap returned by lookup_traps or search_traps, record whether it is still true. Confirmations raise a trap's trust score and disputes lower it; several disputes send it back for review. One vote per trap per 30 days. Needs a free API key.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "footgun": {
    "command": "npx",
    "args": ["-y","@getfootgun/footgun"]
  }
}
```

## Documentation

## What Footgun does

Footgun provides an MCP-accessible registry of verified integration failures. Entries cover issues such as silent deprecations, ineffective settings, and service limits that may not be obvious from normal API documentation. Each trap can include observed symptoms, an explanation of the cause, a corrective code example, the date it was last checked, and a trust score.

The service is intended for two points in a development workflow: before writing code against a provider, and after an integration behaves unexpectedly. Its data is exported from the Footgun registry, where public traps can be added, confirmed, disputed, reviewed, or retired.

## How it works

Use `lookup_traps` with the name of a third-party API, platform, or AI tool before implementing an integration. It returns up to 10 matching failure modes, including symptoms, causes, fixes, examples, and verification dates. When an existing call fails, send the error text to `search_traps`; it returns up to five closely matching traps, ordered by relevance, or no results when the match is weak.

After resolving a previously unknown failure, `file_trap` can create a draft entry. New public filings are checked against official sources, and publication requires confirmation from an official source. Reviewers can still act on a filing while it is being evaluated. Citing provider documentation or changelogs makes a filing easier to verify.

`confirm_trap` records whether a returned trap still applies or should be disputed. Confirmations increase its trust score, while multiple disputes can send it back for review. A trap can be voted on once every 30 days.

## Setup and configuration

The hosted MCP endpoint uses streamable HTTP:

```text
https://getfootgun.com/api/mcp
```

For Claude Code, install the plugin with:

```text
/plugin marketplace add getfootgun/footgun
/plugin install footgun@footgun
```

Other MCP clients can connect their streamable-HTTP configuration to the endpoint. Add `Authorization: Bearer <your key>` when using authenticated filing or confirmation features. Lookups and basic filing work without an account; confirming traps requires a free API key, while private filing requires a Pro or Team key.

The repository also includes a command-line scanner distributed as `@getfootgun/footgun`. Run `npx @getfootgun/footgun scan [path]` with Node.js 20 or later. The scanner supports JSON output and CI failure thresholds, but it is separate from the four MCP tools described here.

## Tools and capabilities

- `lookup_traps`: Find up to 10 dated, verified traps for a provider before coding.
- `search_traps`: Match an error message to as many as five likely traps.
- `file_trap`: Submit a newly discovered failure for review or verification.
- `confirm_trap`: Confirm or dispute a trap and influence its trust score.
- Streamable-HTTP access through the hosted MCP endpoint.
- Public trap records containing verification dates and trust scores.

## Limitations and notes

Results depend on the registry containing a close match. `search_traps` intentionally returns nothing when no trap matches closely, so an empty response is not a diagnosis of the underlying failure. Public filings are not published until an official source confirms them, and dashboard-only issues may require a manual check.

The separate Claude Code scanner examines exact package versions locally. It sends rule downloads and an anonymous finding count, not project source code; watch mode sends package metadata and finding locations rather than code. Trap data is licensed under CC BY 4.0, while the plugin files use the MIT license.

_Full upstream README: https://allmcps.com/mcp/footgun/readme_