# Shodan [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/pipeworx-io/mcp-shodan  
**GitHub Stars:** 0  
**npm Downloads (last month):** 322  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shodan

## Description
Shodan MCP — wraps the full Shodan REST API (api.shodan.io)

## Tools
Capabilities this server exposes over MCP:

- **shodan_host** — What's exposed on IP <ip> — open ports, services, and CVEs. Returns the full Shodan host profile: ports, hostnames, org/ISP, geolocation, OS, known vulnerabilities, and a per-service banner sample. Example: shodan_host({ ip: "8.8.8.8", _apiKey: "your-key" })
- **shodan_host_search** — Search Shodan for hosts matching <query> using Shodan search syntax (e.g. "apache country:US", "port:22 org:\"Google\""). Returns matching hosts with IP, port, org, hostnames, product, and location. Example: shodan_host_search({ query: "apache country:US", _apiKey: "your-key" })
- **shodan_host_count** — Count hosts matching <query> with facet breakdown (free — this endpoint does not consume query credits). Returns the total match count plus optional facet aggregations (e.g. top countries, orgs, ports). Example: shodan_host_count({ query: "apache", facets: "country:10", _apiKey: "your-key" })

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

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

## Documentation

## 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:

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

The local stdio option uses the npm package:

```json
{
  "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.

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