shodan-mcp

Serwer MCP udostepniajacy API Shodan.IO, oparty o FastMCP i oficjalna biblioteke shodan-python.

Wymagania

• Python 3.13+
• uv
• Klucz API Shodan

Instalacja

uv sync

Konfiguracja klucza API

Klucz pobierany jest wylacznie ze zmiennej srodowiskowej SHODAN_API_KEY. Nie zapisuj klucza w repozytorium. Do lokalnych testow skopiuj .env.example do .env.

Uruchomienie

Transport: stdio (domyslny dla lokalnego Claude Code / Claude Desktop).

SHODAN_API_KEY=... uv run server.py

Konfiguracja klienta MCP

Przyklad wpisu (.mcp.json lub claude mcp add):

{
  "mcpServers": {
    "shodan": {
      "command": "uv",
      "args": ["run", "--directory", "/home/ra/secra/shodan-mcp", "server.py"]
    }
  }
}

Tool: search

Generalne wyszukiwanie przez API Shodan. Laczy wolny tekst (query) z opcjonalnymi filtrami-dorkami, ktore tool sklada w finalne zapytanie Shodan.

Obslugiwane filtry: org, hostname, net, ip, port, country, city, product, version, os, asn, isp, title (http.title), http_status (http.status), ssl, vuln, tag, after, before, has_screenshot.

Dodatkowe parametry: page (strona wynikow), facets (agregacje, np. port:10,org:5), raw (gdy true, zwraca pelny surowy JSON zamiast przycietego zestawu pol).

Przyklad: query="nginx", country="PL", port=443 -> zapytanie nginx country:PL port:443.

Tool: host

Lookup po adresie IP. Zwraca szczegoly hosta (org, isp, asn, lokalizacja, porty, tagi, podatnosci) oraz liste wykrytych uslug.

Parametry: ip (wymagany), history (pelna historia banerow), minify (okrojony zestaw pol), raw (pelny surowy JSON zamiast przycietego).

Roadmap

Kolejne toole: count (sam licznik), search_cursor (paginacja kursorowa), scan / alerts.