Shodan

What Shodan does

Shodan provides MCP access to Shodan data for examining exposed internet-facing hosts and discovering assets that match a query. The integration focuses on three operations: retrieving a host profile by IP address, searching hosts with Shodan search syntax, and counting matching hosts with optional facet breakdowns.

A host lookup can include open ports, services, hostnames, organization and ISP information, geolocation, operating system details, known vulnerabilities, and a sample banner for each service. Search results can include the matching IP, port, organization, hostnames, product, and location.

How it works

The hosted connection is available at https://gateway.pipeworx.io/shodan/mcp. It uses the Pipeworx gateway to reach the Shodan REST API, and the Shodan API key is passed in the tool request as _apiKey. The same gateway also exposes shared Pipeworx meta-tools on the hosted pack endpoint, including ask_pipeworx, discover_tools, search_within, and memory-related tools.

A local npm bridge runs over stdio and forwards calls to the hosted gateway. It still needs network access; it does not provide an offline implementation. The gateway can also be connected at its full endpoint when an application needs direct access to all available packs.

Setup and configuration

For an HTTP-capable MCP client, add the hosted endpoint to the client configuration:

{
  "mcpServers": {
    "shodan": {
      "url": "https://gateway.pipeworx.io/shodan/mcp"
    }
  }
}

The local stdio option uses the npm package:

{
  "mcpServers": {
    "shodan": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-shodan"]
    }
  }
}

Add PIPEWORX_API_KEY under the stdio server's env object to authenticate with Pipeworx. The Shodan credential itself is supplied to calls as _apiKey. Anonymous stdio use is limited to 50 calls per day, while a free Pipeworx account raises the limit to 200 calls per day.

Set PIPEWORX_META_TOOLS=1 if the local bridge should also list the gateway-wide meta-tools. Proxy users may need NODE_USE_ENV_PROXY=1, because Node's built-in fetch does not read HTTPS_PROXY by default.

Tools and capabilities

• shodan_host: Retrieve a host profile for an IP, including ports, services, banners, ownership, geography, operating system data, and known CVEs.
• shodan_host_search: Search using Shodan syntax such as apache country:US or port:22 org:"Google".
• shodan_host_count: Count matches and request facet aggregations such as countries, organizations, or ports. This endpoint does not consume query credits.
• ask_pipeworx: Ask a natural-language question through the gateway, which selects and fills the relevant tool arguments.

Limitations and notes

This is an independent, unofficial integration and is not affiliated with Shodan. The hosted pack endpoint lists its three Shodan tools alongside shared gateway tools, so the total tool count is larger than the pack-specific list. Tool scope can change, and the connection's initialize response is authoritative for the tools exposed at connection time.

Calls require network access and an API key for Shodan operations. The integration does not front a Shodan key for HTTP examples, and anonymous local use has a daily call cap. Query searches use Shodan's own search syntax and return the fields supplied by Shodan.