Shodan MCP Server

Instructions

Implementation Reference

• src/index.ts:1586-1612 (handler)

  MCP server handler for executing the 'parse_search_tokens' tool. Validates input query, calls the ShodanClient helper method, formats the response as JSON text content, and handles errors.

  case "parse_search_tokens": {
    const query = String(request.params.arguments?.query);
    if (!query) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Search query is required"
      );
    }
  
    try {
      const tokens = await shodanClient.parseSearchTokens(query);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(tokens, null, 2)
        }]
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Error parsing search tokens: ${(error as Error).message}`
      );
    }
  }

• src/index.ts:400-415 (helper)

  ShodanClient helper method that performs the actual API call to Shodan's parse tokens endpoint (/shodan/host/search/tokens). Returns the parsed tokens or throws MCPError on failure.

  async parseSearchTokens(query: string): Promise<any> {
    try {
      const response = await this.axiosInstance.get("/shodan/host/search/tokens", {
        params: { query }
      });
      return response.data;
    } catch (error: unknown) {
      if (axios.isAxiosError(error)) {
        throw new McpError(
          ErrorCode.InternalError,
          `Shodan API error: ${error.response?.data?.error || error.message}`
        );
      }
      throw error;
    }
  }

• src/index.ts:1042-1054 (registration)

  Tool registration entry in the ListToolsRequestSchema handler. Defines the tool name, description, and input schema for clients to discover and use the tool.

    name: "parse_search_tokens",
    description: "Parse a search query to understand which filters and parameters are being used",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Shodan search query to parse and analyze"
        }
      },
      required: ["query"]
    }
  },

• src/index.ts:1045-1053 (schema)

  Input schema definition for the parse_search_tokens tool, specifying the required 'query' string parameter.

    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Shodan search query to parse and analyze"
      }
    },
    required: ["query"]
  }