@burtthecoder/mcp-shodan 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Burt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# Shodan MCP Server
+
+A Model Context Protocol (MCP) server for querying the [Shodan API](https://shodan.io). This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, and more. It is designed to integrate seamlessly with MCP-compatible applications like [Claude Desktop](https://claude.ai).
+
+## Features
+
+- **IP Lookup**: Retrieve detailed information about an IP address
+- **Search**: Search for devices on Shodan matching specific queries
+- **Ports**: Get a list of ports that Shodan is scanning
+- **Vulnerabilities**: Fetch information about known vulnerabilities (CVE)
+- **DNS Lookup**: Resolve hostnames to IP addresses
+
+## Tools
+
+### 1. IP Lookup Tool
+- Name: `ip_lookup`
+- Description: Retrieve detailed information about an IP address
+- Parameters:
+  * `ip` (required): IP address to lookup
+
+### 2. Search Tool
+- Name: `search`
+- Description: Search for devices on Shodan
+- Parameters:
+  * `query` (required): Shodan search query
+  * `max_results` (optional, default: 10): Number of results to return
+
+### 3. Vulnerabilities Tool
+- Name: `vulnerabilities`
+- Description: Fetch information about known vulnerabilities
+- Parameters:
+  * `cve` (required): CVE identifier
+
+### 4. DNS Lookup Tool
+- Name: `dns_lookup`
+- Description: Resolve hostnames to IP addresses
+- Parameters:
+  * `hostnames` (required): Array of hostnames to resolve
+
+## Requirements
+
+- Node.js (v18 or later)
+- A valid [Shodan API Key](https://account.shodan.io/)
+
+## Setup Guide
+
+### 1. Installation
+
+```bash
+git clone <repository_url>
+cd mcp-shodan
+npm install
+```
+
+### 2. Configuration
+
+Create a `.env` file in the root directory:
+```
+SHODAN_API_KEY=your_shodan_api_key
+```
+
+### 3. Build and Run
+
+```bash
+npm run build
+npm start
+```
+
+### 4. Configure Claude Desktop
+
+There are two ways to configure the Shodan MCP server in Claude Desktop:
+
+#### Option 1: Direct Node Execution (Local Development)
+```json
+{
+  "mcpServers": {
+    "shodan-mcp": {
+      "command": "node",
+      "args": ["path/to/mcp-shodan/build/index.js"],
+      "env": {
+        "SHODAN_API_KEY": "your_shodan_api_key",
+        "DEBUG": "*"
+      }
+    }
+  }
+}
+```
+
+#### Option 2: NPX Installation (Recommended for Users)
+```json
+{
+  "mcpServers": {
+    "shodan-mcp": {
+      "command": "npx",
+      "args": ["@burtthecoder/mcp-shodan"],
+      "env": {
+        "SHODAN_API_KEY": "your_shodan_api_key",
+        "DEBUG": "*"
+      }
+    }
+  }
+}
+```
+
+The npx method automatically downloads and runs the latest version of the package from npm.
+
+Configuration file location:
+
+Windows: %APPDATA%\Claude\claude_desktop_config.json
+macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+
+## Usage
+
+1. Start the MCP server:
+```bash
+npm start
+```
+
+2. Launch Claude Desktop and ensure the Shodan MCP server is detected
+3. Use any of the available tools through the Claude interface
+
+## Development
+
+To run in development mode with hot reloading:
+```bash
+npm run dev
+```
+
+## Error Handling
+
+The server includes comprehensive error handling for:
+- Invalid API keys
+- Rate limiting
+- Network errors
+- Invalid input parameters
+
+## Version History
+
+- v1.0.0: Initial release with core functionality
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/build/index.js

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import axios from "axios";
+import dotenv from "dotenv";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import fs from "fs";
+dotenv.config();
+const logFilePath = "E:/dev/shodan-mcp/server.log";
+const SHODAN_API_KEY = process.env.SHODAN_API_KEY;
+if (!SHODAN_API_KEY) {
+    throw new Error("SHODAN_API_KEY environment variable is required.");
+}
+const API_BASE_URL = "https://api.shodan.io";
+// Logging Helper Function
+function logToFile(message) {
+    const timestamp = new Date().toISOString();
+    const formattedMessage = `[${timestamp}] ${message}\n`;
+    fs.appendFileSync(logFilePath, formattedMessage, "utf8");
+    console.error(formattedMessage.trim()); // Use stderr for logging to avoid interfering with stdout
+}
+// Tool Schemas
+const IpLookupArgsSchema = z.object({
+    ip: z.string().describe("The IP address to query."),
+});
+const SearchArgsSchema = z.object({
+    query: z.string().describe("Search query for Shodan."),
+    max_results: z
+        .number()
+        .optional()
+        .default(10)
+        .describe("Maximum results to return."),
+});
+const VulnerabilitiesArgsSchema = z.object({
+    cve: z.string().describe("The CVE identifier to query."),
+});
+const DnsLookupArgsSchema = z.object({
+    hostnames: z.array(z.string()).describe("List of hostnames to resolve."),
+});
+// Helper Function to Query Shodan API
+async function queryShodan(endpoint, params) {
+    try {
+        const response = await axios.get(`${API_BASE_URL}${endpoint}`, {
+            params: { ...params, key: SHODAN_API_KEY },
+            timeout: 10000,
+        });
+        return response.data;
+    }
+    catch (error) {
+        const errorMessage = error.response?.data?.error || error.message;
+        logToFile(`Shodan API error: ${errorMessage}`);
+        throw new Error(`Shodan API error: ${errorMessage}`);
+    }
+}
+// Server Setup
+const server = new Server({
+    name: "shodan-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {
+            listChanged: true,
+        },
+    },
+});
+// Handle Initialization
+server.setRequestHandler(InitializeRequestSchema, async (request) => {
+    logToFile("Received initialize request.");
+    return {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+            tools: {
+                listChanged: true,
+            },
+        },
+        serverInfo: {
+            name: "shodan-mcp",
+            version: "1.0.0",
+        },
+        instructions: "This server provides tools for querying Shodan, including IP lookups, searches, and vulnerabilities.",
+    };
+});
+// Register Tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = [
+        {
+            name: "ip_lookup",
+            description: "Retrieve information about an IP address.",
+            inputSchema: zodToJsonSchema(IpLookupArgsSchema),
+        },
+        {
+            name: "search",
+            description: "Search for devices on Shodan.",
+            inputSchema: zodToJsonSchema(SearchArgsSchema),
+        },
+        {
+            name: "vulnerabilities",
+            description: "Retrieve vulnerability information for a CVE.",
+            inputSchema: zodToJsonSchema(VulnerabilitiesArgsSchema),
+        },
+        {
+            name: "dns_lookup",
+            description: "Perform DNS lookups using Shodan.",
+            inputSchema: zodToJsonSchema(DnsLookupArgsSchema),
+        },
+    ];
+    logToFile("Registered tools.");
+    return { tools };
+});
+// Handle Tool Calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    logToFile(`Tool called: ${request.params.name}`);
+    try {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            case "ip_lookup": {
+                const parsedIpArgs = IpLookupArgsSchema.safeParse(args);
+                if (!parsedIpArgs.success) {
+                    throw new Error("Invalid ip_lookup arguments");
+                }
+                const result = await queryShodan(`/shodan/host/${parsedIpArgs.data.ip}`, {});
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "search": {
+                const parsedSearchArgs = SearchArgsSchema.safeParse(args);
+                if (!parsedSearchArgs.success) {
+                    throw new Error("Invalid search arguments");
+                }
+                const result = await queryShodan("/shodan/host/search", {
+                    query: parsedSearchArgs.data.query,
+                    limit: parsedSearchArgs.data.max_results,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "vulnerabilities": {
+                const parsedVulnArgs = VulnerabilitiesArgsSchema.safeParse(args);
+                if (!parsedVulnArgs.success) {
+                    throw new Error("Invalid vulnerabilities arguments");
+                }
+                const result = await queryShodan(`/shodan/cve/${parsedVulnArgs.data.cve}`, {});
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "dns_lookup": {
+                const parsedDnsArgs = DnsLookupArgsSchema.safeParse(args);
+                if (!parsedDnsArgs.success) {
+                    throw new Error("Invalid dns_lookup arguments");
+                }
+                // Ensure proper formatting of hostnames for the API request
+                const hostnamesString = parsedDnsArgs.data.hostnames.join(",");
+                // Log the request parameters for debugging
+                logToFile(`DNS lookup request parameters: ${JSON.stringify({ hostnames: hostnamesString })}`);
+                const result = await queryShodan("/dns/resolve", {
+                    hostnames: hostnamesString
+                });
+                // Log the raw response for debugging
+                logToFile(`DNS lookup raw response: ${JSON.stringify(result)}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(result, null, 2)
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logToFile(`Error handling tool call: ${errorMessage}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the Server
+async function runServer() {
+    logToFile("Starting Shodan MCP Server...");
+    try {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logToFile("Shodan MCP Server is running.");
+    }
+    catch (error) {
+        logToFile(`Error connecting server: ${error.message}`);
+        process.exit(1);
+    }
+}
+// Handle process events
+process.on('uncaughtException', (error) => {
+    logToFile(`Uncaught exception: ${error.message}`);
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    logToFile(`Unhandled rejection: ${reason}`);
+    process.exit(1);
+});
+runServer().catch((error) => {
+    logToFile(`Fatal error: ${error.message}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "type": "module",
+  "name": "@burtthecoder/mcp-shodan",
+  "version": "1.0.4",
+  "description": "A Model Context Protocol server for Shodan API queries.",
+  "main": "./build/index.js",
+  "bin": {
+    "mcp-shodan": "build/index.js"
+  },
+  "scripts": {
+    "start": "node build/index.js",
+    "dev": "ts-node src/index.ts",
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.6.0",
+    "axios": "^1.7.8",
+    "dotenv": "^16.4.5",
+    "zod": "^3.22.2",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.24"
+  },
+  "files": [
+    "build"
+  ],
+  "author": "BurtTheCoder",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BurtTheCoder/mcp-shodan.git"
+  },
+  "keywords": [
+    "mcp",
+    "shodan",
+    "mcp-shodan",
+    "cybersecurity",
+    "agents",
+    "network-reconnaissance",
+    "security-tools",
+    "shodan-api",
+    "shodan-integraton"
+  ],
+  "bugs": {
+    "url": "https://github.com/BurtTheCoder/mcp-shodan/issues"
+  },
+  "homepage": "https://github.com/BurtTheCoder/mcp-shodan#readme"
+}