├── Dockerfile ├── LICENSE ├── README.MD ├── README.md ├── package.json ├── smithery.yaml ├── src └── index.ts └── tsconfig.json /Dockerfile: -------------------------------------------------------------------------------- 1 | # Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile 2 | # Use an official Node.js runtime as a parent image 3 | FROM node:18-buster-slim AS builder 4 | 5 | # Set the working directory to /app 6 | WORKDIR /app 7 | 8 | # Copy the current directory contents into the container at /app 9 | COPY . . 10 | 11 | # Install any needed packages specified in package.json 12 | RUN npm install --ignore-scripts 13 | 14 | # Run the TypeScript build to create the dist folder 15 | RUN npm run build 16 | 17 | # Use a lightweight Node.js runtime for the production environment 18 | FROM node:18-buster-slim AS runtime 19 | 20 | # Set the working directory to /app 21 | WORKDIR /app 22 | 23 | # Copy the dist folder from the builder stage 24 | COPY --from=builder /app/dist /app/dist 25 | 26 | # Copy the package.json file to include any runtime dependencies 27 | COPY --from=builder /app/package.json /app/package.json 28 | 29 | # Install only the production dependencies 30 | RUN npm ci --omit=dev 31 | 32 | # Set environment variables if needed 33 | # ENV NODE_ENV=production 34 | 35 | # The command to run the MCP server 36 | ENTRYPOINT ["node", "dist/index.js"] 37 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 PhialsBasement 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.MD: -------------------------------------------------------------------------------- 1 | # MCP NMAP Server 2 | 3 | A Model Context Protocol (MCP) server that enables AI assistants to perform network scanning operations using NMAP. This server provides a standardized interface for AI models to interact with NMAP, making it possible to perform network analysis and security assessments through AI conversations. 4 | 5 | ## Prerequisites 6 | 7 | - Windows operating system 8 | - Node.js (v18 or higher) 9 | - NMAP installed and accessible from Windows command line 10 | - TypeScript for development 11 | 12 | ## Installation 13 | 14 | Install the package globally using npm: 15 | 16 | ```bash 17 | npm install -g mcp-nmap-server 18 | ``` 19 | 20 | Or install locally in your project: 21 | 22 | ```bash 23 | npm install mcp-nmap-server 24 | ``` 25 | 26 | ## Features 27 | 28 | The server provides access to NMAP's core functionality through a simple interface. It supports quick scans, full port scans, version detection, and custom timing templates. The implementation uses NMAP's native command-line interface, ensuring reliability and consistency with standard NMAP operations. 29 | 30 | ## Configuration with Claude Desktop 31 | 32 | To use this server with Claude Desktop on Windows, you'll need to configure it in the Claude configuration file located at: 33 | `C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\config.json` 34 | 35 | Add the NMAP server to your configuration by adding it to the `mcpServers` section. Here's a complete example of a Claude Desktop configuration file: 36 | 37 | ```json 38 | { 39 | "mcpServers": { 40 | "nmap": { 41 | "command": "node", 42 | "args": [ 43 | "C:\\Users\\YOUR_USERNAME\\Downloads\\mcp-nmap-server\\dist\\index.js" 44 | ] 45 | } 46 | }, 47 | "globalShortcut": "Ctrl+Q" 48 | } 49 | ``` 50 | 51 | Replace `YOUR_USERNAME` with your Windows username and adjust the path to where you've installed the NMAP server. 52 | 53 | ## Usage with AI 54 | 55 | Once configured, AI assistants like Claude can use the server through the `run_nmap_scan` function. The function accepts the following parameters: 56 | 57 | ```typescript 58 | { 59 | target: string; // Host or network to scan 60 | ports?: string; // Optional port specification (e.g., "80,443" or "1-1000") 61 | scanType?: 'quick' | 'full' | 'version'; // Scan type (default: 'quick') 62 | timing?: number; // NMAP timing template 0-5 (default: 3) 63 | additionalFlags?: string; // Optional additional NMAP flags 64 | } 65 | ``` 66 | 67 | Example conversation with Claude: 68 | 69 | ``` 70 | Human: Can you scan localhost for open ports? 71 | 72 | Claude: I'll help you scan localhost using NMAP. 73 | 74 | 75 | target: "localhost" 76 | scanType: "quick" 77 | timing: 3 78 | ``` 79 | 80 | 81 | ## License 82 | 83 | MIT License 84 | 85 | ## Support 86 | 87 | For issues, suggestions, or contributions, please visit the GitHub repository. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # MCP NMAP Server 2 | 3 | [![smithery badge](https://smithery.ai/badge/mcp-nmap-server)](https://smithery.ai/server/mcp-nmap-server) 4 | 5 | A Model Context Protocol (MCP) server that enables AI assistants to perform network scanning operations using NMAP. This server provides a standardized interface for AI models to interact with NMAP, making it possible to perform network analysis and security assessments through AI conversations. 6 | 7 | ## Prerequisites 8 | 9 | - Windows operating system 10 | - Node.js (v18 or higher) 11 | - NMAP installed and accessible from Windows command line 12 | - TypeScript for development 13 | 14 | ## Installation 15 | 16 | ### Installing via Smithery 17 | 18 | To install NMAP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-nmap-server): 19 | 20 | ```bash 21 | npx -y @smithery/cli install mcp-nmap-server --client claude 22 | ``` 23 | 24 | ### Manual Installation 25 | Install the package globally using npm: 26 | 27 | ```bash 28 | npm install -g mcp-nmap-server 29 | ``` 30 | 31 | Or install locally in your project: 32 | 33 | ```bash 34 | npm install mcp-nmap-server 35 | ``` 36 | 37 | ## Features 38 | 39 | The server provides access to NMAP's core functionality through a simple interface. It supports quick scans, full port scans, version detection, and custom timing templates. The implementation uses NMAP's native command-line interface, ensuring reliability and consistency with standard NMAP operations. 40 | 41 | ## Configuration with Claude Desktop 42 | 43 | To use this server with Claude Desktop on Windows, you'll need to configure it in the Claude configuration file located at: 44 | `C:\Users\YOUR_USERNAME\AppData\Roaming\Claude\config.json` 45 | 46 | Add the NMAP server to your configuration by adding it to the `mcpServers` section. Here's a complete example of a Claude Desktop configuration file: 47 | 48 | ```json 49 | { 50 | "mcpServers": { 51 | "nmap": { 52 | "command": "node", 53 | "args": [ 54 | "C:\\Users\\YOUR_USERNAME\\Downloads\\mcp-nmap-server\\dist\\index.js" 55 | ] 56 | } 57 | }, 58 | "globalShortcut": "Ctrl+Q" 59 | } 60 | ``` 61 | 62 | Replace `YOUR_USERNAME` with your Windows username and adjust the path to where you've installed the NMAP server. 63 | 64 | ## Usage with AI 65 | 66 | Once configured, AI assistants like Claude can use the server through the `run_nmap_scan` function. The function accepts the following parameters: 67 | 68 | ```typescript 69 | { 70 | target: string; // Host or network to scan 71 | ports?: string; // Optional port specification (e.g., "80,443" or "1-1000") 72 | scanType?: 'quick' | 'full' | 'version'; // Scan type (default: 'quick') 73 | timing?: number; // NMAP timing template 0-5 (default: 3) 74 | additionalFlags?: string; // Optional additional NMAP flags 75 | } 76 | ``` 77 | 78 | Example conversation with Claude: 79 | 80 | ``` 81 | Human: Can you scan localhost for open ports? 82 | 83 | Claude: I'll help you scan localhost using NMAP. 84 | 85 | 86 | target: "localhost" 87 | scanType: "quick" 88 | timing: 3 89 | ``` 90 | 91 | 92 | ## License 93 | 94 | MIT License 95 | 96 | ## Support 97 | 98 | For issues, suggestions, or contributions, please visit the GitHub repository. 99 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "mcp-nmap-server", 3 | "version": "1.0.1", 4 | "description": "MCP server for performing network scanning using NMAP", 5 | "main": "dist/index.js", 6 | "type": "module", 7 | "scripts": { 8 | "build": "tsc", 9 | "prepare": "npm run build" 10 | }, 11 | "keywords": [ 12 | "mcp", 13 | "Model Context Protocol", 14 | "nmap", 15 | "network", 16 | "scanning", 17 | "security", 18 | "port scanning", 19 | "network analysis" 20 | ], 21 | "author": "Phiality", 22 | "license": "MIT", 23 | "dependencies": { 24 | "@modelcontextprotocol/sdk": "1.0.1", 25 | "glob": "^10.3.10", 26 | "zod-to-json-schema": "^3.23.5" 27 | }, 28 | "devDependencies": { 29 | "@types/node": "^20.11.0", 30 | "shx": "^0.3.4", 31 | "ts-node": "^10.9.2", 32 | "typescript": "^5.3.3" 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /smithery.yaml: -------------------------------------------------------------------------------- 1 | # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml 2 | 3 | startCommand: 4 | type: stdio 5 | configSchema: 6 | # JSON Schema defining the configuration options for the MCP. 7 | type: object 8 | required: 9 | - target 10 | properties: 11 | target: 12 | type: string 13 | description: Host or network to scan 14 | ports: 15 | type: string 16 | description: Port specification (e.g., '80,443' or '1-1000') 17 | scanType: 18 | type: string 19 | default: quick 20 | description: "Scan type: 'quick', 'full', 'version'" 21 | timing: 22 | type: number 23 | default: 3 24 | description: NMAP timing template 0-5 25 | additionalFlags: 26 | type: string 27 | description: Optional additional NMAP flags 28 | commandFunction: 29 | # A function that produces the CLI command to start the MCP on stdio. 30 | |- 31 | (config) => ({ command: 'node', args: ['dist/index.js'], env: {} }) 32 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | import { Server } from "@modelcontextprotocol/sdk/server/index.js"; 3 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; 4 | import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js"; 5 | import { z } from "zod"; 6 | import { zodToJsonSchema } from "zod-to-json-schema"; 7 | import { exec } from 'child_process'; 8 | import { promisify } from 'util'; 9 | 10 | const execAsync = promisify(exec); 11 | 12 | // Schema definitions for NMAP scanning 13 | const NmapScanSchema = z.object({ 14 | target: z.string(), 15 | ports: z.string().optional(), // e.g. "22-80" or "80,443" or null for default 16 | scanType: z.enum(['quick', 'full', 'version']).default('quick'), 17 | timing: z.number().min(0).max(5).default(3), // T0-T5 timing templates 18 | additionalFlags: z.string().optional() 19 | }); 20 | 21 | const server = new Server({ 22 | name: "nmap-server", 23 | version: "0.1.0", 24 | }, { 25 | capabilities: { 26 | tools: {}, 27 | }, 28 | }); 29 | 30 | async function runNmapScan(params: z.infer) { 31 | const { target, ports, scanType, timing, additionalFlags } = params; 32 | 33 | // Build the nmap command with proper flags 34 | let command = `nmap -T${timing}`; 35 | 36 | // Add scan type flags 37 | switch (scanType) { 38 | case 'quick': 39 | command += ' -F'; // Fast scan 40 | break; 41 | case 'full': 42 | command += ' -p-'; // All ports 43 | break; 44 | case 'version': 45 | command += ' -sV'; // Version detection 46 | break; 47 | } 48 | 49 | // Add port specification if provided 50 | if (ports) { 51 | command += ` -p${ports}`; 52 | } 53 | 54 | // Add any additional flags 55 | if (additionalFlags) { 56 | command += ` ${additionalFlags}`; 57 | } 58 | 59 | // Add target 60 | command += ` ${target}`; 61 | 62 | try { 63 | const { stdout, stderr } = await execAsync(command); 64 | if (stderr) { 65 | console.error('Nmap stderr:', stderr); 66 | } 67 | return stdout; 68 | } catch (error: unknown) { 69 | const errorMessage = error instanceof Error ? error.message : String(error); 70 | throw new Error(`Nmap scan failed: ${errorMessage}`); 71 | } 72 | } 73 | 74 | // Tool handlers 75 | server.setRequestHandler(ListToolsRequestSchema, async () => { 76 | return { 77 | tools: [ 78 | { 79 | name: "run_nmap_scan", 80 | description: "Run an NMAP scan on a target. Supports various scan types and configurations.", 81 | inputSchema: zodToJsonSchema(NmapScanSchema), 82 | } 83 | ], 84 | }; 85 | }); 86 | 87 | server.setRequestHandler(CallToolRequestSchema, async (request) => { 88 | try { 89 | const { name, arguments: args } = request.params; 90 | 91 | if (name === "run_nmap_scan") { 92 | const parsed = NmapScanSchema.safeParse(args); 93 | if (!parsed.success) { 94 | throw new Error(`Invalid arguments for run_nmap_scan: ${parsed.error}`); 95 | } 96 | 97 | const result = await runNmapScan(parsed.data); 98 | 99 | return { 100 | content: [{ 101 | type: "text", 102 | text: result 103 | }], 104 | isError: false, 105 | }; 106 | } 107 | 108 | throw new Error(`Unknown tool: ${name}`); 109 | } catch (error) { 110 | const errorMessage = error instanceof Error ? error.message : String(error); 111 | return { 112 | content: [{ type: "text", text: `Error: ${errorMessage}` }], 113 | isError: true, 114 | }; 115 | } 116 | }); 117 | 118 | // Start server 119 | async function runServer() { 120 | const transport = new StdioServerTransport(); 121 | await server.connect(transport); 122 | console.error("NMAP server running on stdio"); 123 | } 124 | 125 | runServer().catch((error) => { 126 | console.error("Fatal error running server:", error); 127 | process.exit(1); 128 | }); -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | 3 | "compilerOptions": { 4 | 5 | "target": "es2020", 6 | 7 | "module": "es2020", 8 | 9 | "moduleResolution": "node", 10 | 11 | "outDir": "./dist", 12 | 13 | "rootDir": "./src", 14 | 15 | "strict": true, 16 | 17 | "esModuleInterop": true, 18 | 19 | "skipLibCheck": true, 20 | 21 | "forceConsistentCasingInFileNames": true 22 | 23 | }, 24 | 25 | "include": ["src/**/*"], 26 | 27 | "exclude": ["node_modules", "dist"] 28 | 29 | } --------------------------------------------------------------------------------