How to integrate Shodan MCP with Hermes

Connect Hermes to Shodan MCP. Search shodan for exposed apache servers, inspect shodan host details for 8.8.8.8, and more using natural language, with authentication handled for you.

Shodan logoShodan
Api Key

Shodan is an Internet intelligence service for discovering exposed devices and services. It helps security teams search host data and monitor network exposure.

45 Tools

Introduction

Hermes is a 24/7 autonomous agent that lives on your computer or server — it remembers what it learns and evolves as your usage grows.

This guide explains the easiest and most robust way to connect your Shodan account to Hermes. You can do this through either Composio Connect CLI or Composio Connect MCP. For personal use we recommend the CLI, but you won't go wrong with MCP either.

For exact tool slugs and parameter tables, see the tool catalog in the Composio docs.

Also integrate Shodan with

What is Composio Connect?

Composio Connect is a consumer offering that lets anyone plug 1,700+ applications directly into their agent harness — including Hermes. It can:

  • Search and load tools from relevant toolkits on-demand, reducing context usage.
  • Chain multiple tools to accomplish complex workflows via a remote workbench, without excessive back-and-forth with the LLM.
  • Manage app authentication end-to-end with zero manual overhead.

Integrating Shodan with Hermes

Using Composio Connect CLI

1. Install the Composio CLI

Run the install script directly, or paste https://composio.dev/hermes into your Hermes chat box to have it installed for you.

bash
curl -fsSL https://composio.dev/install | bash
Hermes authenticating with Composio

2. Authenticate

Once the CLI is installed, ask Hermes to authenticate with Composio.

3. Connect to Shodan

Ask your agent to connect to Shodan, or simply request any Shodan-related task. Hermes will prompt you to authenticate and authorize access.

4. Done. You're all set with a new Shodan connection.


Using Composio Connect MCP

1. Get your MCP URL and API Key

Go to dashboard.composio.dev and copy your Connect MCP URL and API key.

Copy MCP URL and API key from Composio dashboard

2. Open the Hermes config file

bash
nano ~/.hermes/config.yaml

3. Add the Composio Connect MCP server

bash
mcp_servers:
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "YOUR_COMPOSIO_API_KEY"
    connect_timeout: 60
    timeout: 180

Save with Ctrl + O, Enter, then exit with Ctrl + X.

4. Restart your Hermes agent

Once restarted, ask your agent to connect to Shodan or request any Shodan-related task. It will prompt you to authenticate and authorize access.

5. Done!

What is the Shodan MCP server, and what's possible with it?

The Shodan MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Shodan account. It provides structured and secure access to Shodan's internet intelligence, host data, network monitoring, scans, and account tools, so your agent can search exposed services, inspect hosts, monitor IP ranges, and investigate domains on your behalf.

  • Internet exposure discovery: Have your agent search Shodan for hosts and services matching specific queries, count matching hosts, and review service observations for individual IP addresses.
  • Domain and DNS investigation: Direct your agent to find subdomains and DNS records, resolve hostnames to IP addresses, or look up hostnames associated with IP addresses.
  • Network exposure monitoring: Let the agent create and manage monitoring alerts for IP addresses or CIDR ranges, configure alert triggers, and connect notification services for matching events.
  • On-demand scanning: Instruct your agent to request scans for selected IP addresses or CIDR ranges, submit internet-wide scans for supported ports and protocols, and check scan status.
  • Shodan account and search guidance: Have your agent review plan usage, account profile details, available search filters and facets, crawled ports, scan protocols, saved queries, and supported notifier providers.

Way Forward

With Shodan connected, Hermes can now act on your behalf whenever it detects a relevant task or you ask it to.

From here, you can extend Hermes further:

  • Connect more apps: Calendar, Slack, Notion, Linear, and hundreds of others are available through the same Composio Connect setup. Each new integration compounds what Hermes can do for you.
  • Build workflows across tools: Once multiple apps are connected, Hermes can chain actions together — turn an email into a calendar invite, a Slack message into a Linear ticket, or a meeting note into a follow-up draft.
  • Let it learn your patterns: The more you use Hermes, the better it gets at anticipating how you'd handle recurring tasks. Give it feedback on drafts and decisions, and it will adapt.

If you run into trouble or want to share what you've built, join the community or check out the Docs for deeper configuration options.

TOOLS

Supported Tools

Every Shodan action and event your agent gets out of the box.

Add Alert Notifier

Attach an existing notifier to a paid Shodan network alert.

Add Organization Member

Add a Shodan user to the connected Enterprise organization and upgrade their account, granting organization access.

Count Hosts

Count hosts matching a Shodan search query and optionally return facet counts, without returning banners or consuming query credits for a plain count.

Create Network Alert

Create continuous Shodan monitoring for specified IP addresses or CIDR ranges.

Create Notifier

Create a reusable Shodan notification destination.

Delete Network Alert

Permanently delete a Shodan network alert and stop monitoring its configured IP addresses or CIDR ranges.

Delete Notifier

Permanently delete a Shodan notification service.

Disable Alert Trigger

Disable one or more trigger rules on a paid Shodan network alert.

Enable Alert Trigger

Enable one or more trigger rules on a paid Shodan network alert.

Get Account Profile

Return membership status, credits, display name, username, creation time, and additional profile fields for the owner of the connected Shodan API key.

Get API Plan Information

Return the connected API key's Shodan plan, query and scan credits, monitored-IP allowance, usage limits, and unlocked protocol features.

Get Domain Information

Return one page of subdomains and DNS records for a domain.

Get Execution Egress IP

Return the public source IP address Shodan observes for this API request.

Get Host Information

Return Shodan's current or historical service observations for one IP address.

Get Network Alert

Get one Shodan network alert, including its filters, triggers, and attached notifiers.

Get Notifier

Get one Shodan notification service and its provider-specific destination arguments.

Get Observed Request Headers

Return the HTTP request headers Shodan observes for this Composio API call.

Get Organization

Return the connected account's Shodan organization, administrators, members, member upgrade, authorized domains, and branding.

Get Scan Status

Return the submission or processing status of one Shodan on-demand scan.

Ignore Alert Service

Add one IP:port service to a Shodan network alert trigger's ignore list so matching events no longer notify.

List Alert Triggers

List trigger rules that can be enabled on Shodan network alerts.

List Crawled Ports

List TCP and UDP port numbers currently crawled by Shodan.

List Dataset Files

List downloadable file metadata for one Shodan bulk dataset.

List Datasets

List bulk Shodan datasets available to the connected account.

List Network Alerts

List network alerts on the connected account, optionally including expired alerts.

List Notifier Providers

List supported notification providers and the provider-specific argument names each requires.

List Notifiers

List notification services available on the connected account.

List Saved Queries

Return one page of community-saved Shodan search queries, with optional vote or timestamp ordering.

List Saved Query Tags

List the most popular tags used by community-saved Shodan queries.

List Scan Protocols

List protocol names and descriptions accepted by Shodan on-demand scan requests.

List Scans

Return one page of active and recent on-demand scans for the connected Shodan account.

List Search Facets

List facet names accepted by Shodan host search.

List Search Filters

List filter names accepted in Shodan host-search query syntax.

Remove Alert Notifier

Detach a notifier from a paid Shodan network alert so future matching events are no longer sent through it.

Remove Organization Member

Permanently remove a member from the connected Shodan Enterprise organization and downgrade their account.

Request Internet Scan

Submit an Internet-wide scan for one port and protocol, initiating external network traffic and consuming scan credits.

Request Scan

Submit an asynchronous Shodan scan for specified IP addresses or CIDR ranges.

Resolve Hostnames

Resolve one or more hostnames to IP addresses.

Reverse DNS Lookup

Look up hostnames for one or more IP addresses.

Search Hosts

Return one page of Shodan banners matching a query, with optional facets and field selection.

Search Saved Queries

Return one page of community-saved Shodan queries matching text.

Tokenize Search Query

Parse a Shodan search query into text, filters, attributes, and syntax errors without running the search.

Unignore Alert Service

Remove one IP:port service from a Shodan network alert trigger's ignore list so matching events can notify again.

Update Network Alert

Replace the complete IP and CIDR range list monitored by an existing Shodan network alert.

Update Notifier

Replace provider-specific arguments for an existing Shodan notifier.

FAQ

Frequently asked questions

Start with Shodan.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Shodan tool your agent needs.Free to start.

Start building