How to integrate Shodan MCP with Atomic Agent

Connect Atomic Agent 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

Atomic Agent is an open-source AI agent that runs on your machine and supports local models through llama.cpp. Connect it to 1,700+ apps through Composio, including Shodan.

This guide uses Atomic Agent's built-in Composio integration. You need Atomic Agent v0.5.6 or later, your own Composio API key, and a Shodan account. See the Atomic Agent documentation for installation instructions.

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

Also integrate Shodan with

How Atomic Agent connects to Shodan

Atomic Agent connects to Composio's Tool Router over Streamable HTTP MCP. It discovers the tools needed for your request, and Composio handles account authentication.

Execution and account-connection tools follow Atomic Agent's configured approval policy. Review any approval prompt before allowing an action on your connected account.

Connect Shodan to Atomic Agent

  1. Sign up or sign in to the Composio dashboard. Copy your API key.
  2. In Atomic Agent, open the Integrations tab and select Composio. Select API key, press e, paste the key, and press Enter. The tools become available immediately, without a restart.
  3. Ask Atomic Agent to do something in Shodan. It searches Composio for the right tool.
  4. On first use, open the sign-in link returned in the chat. Connect your Shodan account, then return to Atomic Agent to continue.

Headless setup

Add the following line to ~/.atomic-agent/.env, replacing YOUR_COMPOSIO_API_KEY with your key. Start Atomic Agent after saving the file.

bash
COMPOSIO_API_KEY=YOUR_COMPOSIO_API_KEY

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.

Use Shodan from Atomic Agent

With your account connected, ask Atomic Agent to work with Shodan in natural language. You can connect more apps through the same Composio integration as you need them.

Visit the Atomic Agent website or inspect the Atomic Agent source code.

Troubleshooting

Why is my API key rejected?

Copy the key directly from the Composio dashboard. Atomic Agent requires ASCII characters because it sends the key in an HTTP header. Remove any extra characters introduced when copying.

Why are Composio tools unavailable after saving a key?

Check that you use Atomic Agent v0.5.6 or later and that Composio is enabled in your configuration. A "composio": { "enabled": false } setting disables the integration while keeping the saved key on disk.

Does Composio have a free plan?

The Hobby plan includes 100,000 tool calls per month. Composio-managed OAuth apps have a lower included allowance. See Composio pricing for the current limits that apply to your connection.

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