Hookdeck CLI
Hookdeck CLI forwards webhooks to a local server, manages Event Gateway and runs an MCP server through which an agent investigates delivery failures
- 369 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- Accepts webhooks from the outside network on a local port, and their contents and headers pass through the Hookdeck cloud service
- Keeps API keys and sign-in data in configuration files, and a CLI key reaches all your projects
- With the --allow-write flag an agent can create, change, delete and retry deliveries in Event Gateway
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/hookdeck-cliDetects the agents on your machine, shows the access level and pins the version.
What it sends to the author: what it sends to the author: the hookdeck cli collects anonymous telemetry to improve the tool. you can disable sending via command or environment variable.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Accepts webhooks from the outside network on a local port, and their contents and headers pass through the Hookdeck cloud service
- Keeps API keys and sign-in data in configuration files, and a CLI key reaches all your projects
- With the --allow-write flag an agent can create, change, delete and retry deliveries in Event Gateway
This is third-party code. Review the repository files before installing.
What it does
Hookdeck CLI is the official command-line tool of the Hookdeck service and covers three tasks. First, `hookdeck listen 3000 stripe` forwards webhooks to a local server through a permanent free event URL, with event history preserved between sessions so you or teammates can view and replay deliveries. Development on Hookdeck is free, and the service charges for production load. The authors call the CLI a replacement for ngrok and other HTTP tunnels, though the approach differs. Second, it manages Event Gateway resources from the terminal: sources, destinations, connections, transformations, events, requests and delivery attempts. You can retry a failed event, create a transformation and test it on sample data, or pause a connection. For CI there is the `hookdeck ci` command and sign-in with a project API key, while `hookdeck login` opens a browser. Third, an MCP server. `hookdeck gateway mcp` runs as a stdio subprocess in Cursor or Claude Desktop and gives an agent tools for investigating traffic: issues, events, requests, attempts, metrics and transformations. By default the server is read-only, and creating, changing and deleting are enabled with the --allow-write flag or the HOOKDECK_MCP_ALLOW_WRITE variable. Pausing a connection works even without write access. A separate `hookdeck outpost mcp` works with the Outpost product: tenants and their destinations.
Who it is for. For developers who receive Stripe, GitHub or Shopify webhooks and want to debug them locally, and for Hookdeck teams that need an agent to investigate delivery failures.
Good fit when
- You need to receive a payment service's webhooks on a local server at a permanent URL that does not change on every launch
- You want to replay a past event on your local server instead of triggering it again at the provider
- An agent should find out why deliveries fail in production: issue list, attempts, 500 errors and failure rates by destination
- You want to create Event Gateway sources, connections and transformations from the terminal or CI and test them on sample data
- You need to keep the agent read-only: the MCP server changes nothing by default and every read tool ends in _read
Not a fit when
- You do not use Hookdeck and do not want an account: the tool works with the Hookdeck service and requires a login or a temporary guest account
- You need a general HTTP tunnel for non-webhook traffic: the tool forwards events, and one process listens to one source
- You want to trust an agent with writes unsupervised: changes need the --allow-write flag, which should be enabled deliberately
- You need an agent to manage API keys: key management is deliberately not exposed through MCP
Example request
Connect the Hookdeck MCP in read-only mode and show whether any delivery issues are open now and which events for my Stripe source ended in an errorLimitations
- A Hookdeck account is needed. Without login, commands like `hookdeck listen` create a temporary guest account.
- One CLI process listens to one source at a time.
- A CLI key reaches all projects while a project key reaches only one, and only a CLI key can list and switch projects.
- The MCP server is read-only by default. Writing is enabled with the --allow-write flag or the HOOKDECK_MCP_ALLOW_WRITE variable, and API key creation and rotation are not exposed through MCP.
- Development is free and production load is paid. The Hookdeck service is cloud-based.
- The documentation has a separate section on telemetry, and settings live in configuration files.
How to disable. `hookdeck logout` signs out and removes saved credentials. Remove the hookdeck block from the MCP client config and restart the client. The tool itself is removed by the package manager you used: npm uninstall -g hookdeck-cli, brew uninstall hookdeck or scoop uninstall hookdeck.
FAQ
How do I receive webhooks on a local server through Hookdeck?
Run hookdeck login, then hookdeck listen 3000 stripe, where 3000 is your server's port and stripe is the source name. The CLI shows a permanent event URL and forwards requests to it. The --path flag changes the path and --output switches among interactive, compact and quiet.
How do I connect Hookdeck MCP to Cursor or Claude Desktop?
Add a hookdeck server to Cursor's mcp.json or claude_desktop_config.json with the command hookdeck and the arguments gateway and mcp. The client starts it as a stdio subprocess. If you have not signed in, the hookdeck_login tool authenticates through the browser.
Can an agent change data in Hookdeck through MCP?
Not by default: the server starts read-only. Changes are enabled with the --allow-write flag or the HOOKDECK_MCP_ALLOW_WRITE=true variable. Pausing and unpausing a connection works without write access because it is reversible. API key management is unavailable through MCP in any mode.
How is Hookdeck CLI different from ngrok?
Hookdeck does not open a general tunnel; it receives events on its side and forwards them to you. The event URL is permanent and free for development, event history persists between sessions and deliveries can be replayed. The authors call the CLI an ngrok replacement though its approach and philosophy differ.
How do I use Hookdeck CLI in CI?
Sign in with a project key using hookdeck ci --api-key, or pass the key to listen with the --api-key flag. Such a key is limited to one project and cannot list projects. Signing in with a user key goes through hookdeck login --cli-key.
Discussion
No questions or reviews yet.
Related
CLI toolsA local dashboard for Claude Code and Codex sessions: who is working, who waits for you, plus a 3D aquarium and Stream Deck
Logs, alerts and container management for Docker and Podman: an MCP server and CLI, with agent rights set by token scope
A secure MCP runtime through which an agent operates local machines, servers and containers
A Node.js manager for MCP servers: it starts local servers, connects remote ones and gives a client one address, with a REST API for control
The remote MCP server of Devopness, a platform that builds infrastructure and deploys apps in your own cloud accounts
A self-hosted gateway that merges several MCP servers into one endpoint with auth and tool selection
README in short
The README explains that the CLI forwards webhooks to a local server and manages Event Gateway resources, and lists installation through npm, Homebrew, Scoop, Linux and Docker. It then describes the login and listen commands in detail, event filters, output modes, CI use, resource management, both MCP servers, configuration files and keys.