# shodan-mcp

Serwer MCP udostepniajacy API Shodan.IO, oparty o [FastMCP](https://gofastmcp.com)
i oficjalna biblioteke [shodan-python](https://shodan.readthedocs.io).

## Wymagania

- Python 3.13+
- [uv](https://docs.astral.sh/uv/)
- Klucz API Shodan

## Instalacja

```bash
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).

```bash
SHODAN_API_KEY=... uv run server.py
```

## Konfiguracja klienta MCP

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

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