Interactsh
Model Context Protocol bridge for interactsh
Ask AI about Interactsh
Powered by Claude Β· Grounded in docs
I know everything about Interactsh. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
A vibe code MCP Interactsh Bridge
This project exposes ProjectDiscovery's interactsh as a Model Context Protocol server implemented in Node.js. It lets MCP-compatible IDEs or agents provision interactsh sessions, poll for out-of-band interactions, and tear them down without modifying the upstream interactsh codebase.
Features
- Session provisioning β Generates RSA key pairs, registers with the public interactsh fleet, and returns ready-to-use callback domains.
- Polling & decryption β Retrieves encrypted interaction data and decrypts it locally using the session's private key.
- Lifecycle management β Lists cached sessions and deregisters them when finished.
- Demo script β
npm run demospins up a session, issues a real HTTP probe, and prints the captured DNS/HTTP events.
Requirements
- Node.js 18 or newer (tested on Node 20.19)
- Network access to the interactsh fleet (defaults to
https://oast.pro)
Installation (local)
git clone https://github.com/tachote/mcp-interactsh
cd mcp-interactsh
npm install
Run via npx
npx -y mcp-interactsh
You can also pass environment variables inline:
INTERACTSH_BASE_URL=https://oast.pro \
INTERACTSH_DOMAIN_SUFFIX=oast.pro \
npx -y mcp-interactsh
Usage
Run the MCP server
The MCP server communicates over stdio. Configure your MCP-compatible client (e.g. Claude Code, VS Code MCP, Cursor) to launch:
node src/server.js
Optional environment variables:
| Variable | Default | Description |
|---|---|---|
INTERACTSH_BASE_URL | https://oast.pro | Base URL of the interactsh server to target. |
INTERACTSH_DOMAIN_SUFFIX | host derived from INTERACTSH_BASE_URL | Domain suffix used to build callback hosts. Override when using a custom interactsh deployment. |
INTERACTSH_TOKEN | (unset) | Authorization token if your interactsh server enforces auth. |
Available MCP tools
create_interactsh_sessionβ Registers a new session and returns correlation ID, secret key, PEM private key, callback domain, server URL, plus explicit probe instructions.- Probing rules:
- Build host as
<correlation_id><nonce13>.<domain>. correlation_idis exactly 20 lowercase hex chars; do not alter or truncate.nonce13is exactly 13 lowercase alphanumeric chars[a-z0-9].- The label before the first dot must be 33 chars total (20 + 13).
- Requests to
<correlation_id>.<domain>(no nonce) are ignored by interactsh. - Prefer plain HTTP for probes. Wait 2β3 seconds, then poll for events.
- Build host as
- Probing rules:
list_interactsh_sessionsβ Lists all sessions cached in memory for the current MCP process.poll_interactsh_sessionβ Polls interactsh for new interactions, returning decrypted events. Optional arguments let you filter bymethod,path_contains,query_contains,protocol, ortext_containsto focus on specific callbacks.deregister_interactsh_sessionβ Deregisters the session and removes it from local state.
Configure in Claude Code (JSON)
Claude Code supports MCP servers over stdio. If you prefer to configure via JSON, add an entry like the following in your Claude Code settings (Settings β MCP Servers or the equivalent config file):
{
"mcpServers": {
"interactsh": {
"transport": "stdio",
"command": "npx",
"args": ["-y", "mcp-interactsh"],
"env": {
"INTERACTSH_BASE_URL": "https://oast.pro",
"INTERACTSH_DOMAIN_SUFFIX": "oast.pro"
// "INTERACTSH_TOKEN": "your_server_token_if_required"
}
}
}
}
If you prefer to use a local path (without npx), use:
{
"mcpServers": {
"interactsh": {
"transport": "stdio",
"command": "node",
"args": ["/absolute/path/to/src/server.js"],
"env": {
"INTERACTSH_BASE_URL": "https://oast.pro",
"INTERACTSH_DOMAIN_SUFFIX": "oast.pro"
}
}
}
}
Or you can add it with:
claude mcp add --transport stdio interactsh \
-e INTERACTSH_BASE_URL=https://oast.pro \
-e INTERACTSH_DOMAIN_SUFFIX=oast.pro \
-- npx -y mcp-interactsh
Configure in Codex (TOML)
Codex reads MCP server configuration from ~/.codex/config.toml. Add an entry like the following:
[mcp_servers.interactsh]
command = "npx"
args = ["-y", "mcp-interactsh"]
env = { INTERACTSH_BASE_URL = "https://oast.pro", INTERACTSH_DOMAIN_SUFFIX = "oast.pro" }
If you prefer to reference a local clone instead of npx:
[mcp_servers.interactsh]
command = "node"
args = ["/absolute/path/to/src/server.js"]
env = { INTERACTSH_BASE_URL = "https://oast.pro", INTERACTSH_DOMAIN_SUFFIX = "oast.pro" }
Or you can add it with:
codex mcp add --env INTERACTSH_BASE_URL=https://oast.pro --env INTERACTSH_DOMAIN_SUFFIX=oast.pro interactsh -- npx -y mcp-interactsh
You can verify the configuration with:
codex mcp list
codex mcp get interactsh --json
License
Released under the MIT License. See LICENSE for details.
Credits
This bridge builds on the excellent work by ProjectDiscovery. See the original interactsh project:
- Interactsh repository: https://github.com/projectdiscovery/interactsh
