get_host_count
Retrieve the count of hosts matching a Shodan search query without using query credits, optionally including facets like country or organization for detailed insights.
Instructions
Get the count of hosts matching a search query without consuming query credits
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| facets | No | List of facets to include in the count results (e.g., ['country', 'org']) | |
| query | Yes | Shodan search query to count hosts for |
Implementation Reference
- src/index.ts:1503-1544 (handler)MCP server tool handler for 'get_host_count' that validates input parameters, calls the ShodanClient.getHostCount method, handles errors, and returns JSON-formatted response.case "get_host_count": { const query = String(request.params.arguments?.query); if (!query) { throw new McpError( ErrorCode.InvalidParams, "Search query is required" ); } const facets = Array.isArray(request.params.arguments?.facets) ? request.params.arguments?.facets.map(String) : []; try { const hostCount = await shodanClient.getHostCount(query, facets); // Check if we got an error response from the host count method if (hostCount.error && hostCount.status === 401) { return { content: [{ type: "text", text: JSON.stringify(hostCount, null, 2) }] }; } return { content: [{ type: "text", text: JSON.stringify(hostCount, null, 2) }] }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Error getting host count: ${(error as Error).message}` ); } }
- src/index.ts:334-358 (helper)ShodanClient helper method implementing the core logic for getting host count matching a Shodan query by calling the /shodan/host/count API endpoint without consuming query credits.async getHostCount(query: string, facets: string[] = []): Promise<any> { try { const params: any = { query }; if (facets.length > 0) { params.facets = facets.join(','); } const response = await this.axiosInstance.get("/shodan/host/count", { params }); return response.data; } catch (error: unknown) { if (axios.isAxiosError(error)) { if (error.response?.status === 401) { return { error: "Unauthorized: The Shodan search API requires a paid membership. Your API key does not have access to this endpoint.", message: "The host count functionality requires a Shodan membership subscription with API access. Please upgrade your Shodan plan to use this feature.", status: 401 }; } throw new McpError( ErrorCode.InternalError, `Shodan API error: ${error.response?.data?.error || error.message}` ); } throw error; }
- src/index.ts:1005-1023 (registration)Tool registration entry in the ListTools response defining the 'get_host_count' tool name, description, and input schema for validation.name: "get_host_count", description: "Get the count of hosts matching a search query without consuming query credits", inputSchema: { type: "object", properties: { query: { type: "string", description: "Shodan search query to count hosts for" }, facets: { type: "array", items: { type: "string" }, description: "List of facets to include in the count results (e.g., ['country', 'org'])" } }, required: ["query"] }
- src/index.ts:1005-1023 (schema)Input schema definition for the 'get_host_count' tool used for parameter validation in tool calls.name: "get_host_count", description: "Get the count of hosts matching a search query without consuming query credits", inputSchema: { type: "object", properties: { query: { type: "string", description: "Shodan search query to count hosts for" }, facets: { type: "array", items: { type: "string" }, description: "List of facets to include in the count results (e.g., ['country', 'org'])" } }, required: ["query"] }