mcp-server-nmap 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. mcp_server_nmap-0.1.0/.gitignore +26 -0
  2. mcp_server_nmap-0.1.0/LICENSE +21 -0
  3. mcp_server_nmap-0.1.0/PKG-INFO +209 -0
  4. mcp_server_nmap-0.1.0/README.md +169 -0
  5. mcp_server_nmap-0.1.0/pyproject.toml +94 -0
mcp_server_nmap-0.1.0/.gitignore ADDED
@@ -0,0 +1,26 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .eggs/
7
+ *.egg
8
+ .env
9
+ .venv
10
+ venv/
11
+ env/
12
+ *.pyc
13
+ *.pyo
14
+ .pytest_cache/
15
+ .ruff_cache/
16
+ .mypy_cache/
17
+ htmlcov/
18
+ .coverage
19
+ .coverage.*
20
+ *.log
21
+ .DS_Store
22
+ .idea/
23
+ .vscode/
24
+ *.swp
25
+ *.swo
26
+ .hypothesis/
mcp_server_nmap-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dario Clavijo
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.
mcp_server_nmap-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,209 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-server-nmap
3
+ Version: 0.1.0
4
+ Summary: MCP server for python-nmap network scanning
5
+ Project-URL: Homepage, https://github.com/daedalus/mcp-server-nmap
6
+ Project-URL: Repository, https://github.com/daedalus/mcp-server-nmap
7
+ Project-URL: Issues, https://github.com/daedalus/mcp-server-nmap/issues
8
+ Author-email: Dario Clavijo <clavijodario@gmail.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Requires-Python: >=3.11
12
+ Requires-Dist: python-nmap==0.7.1
13
+ Provides-Extra: all
14
+ Requires-Dist: hatch; extra == 'all'
15
+ Requires-Dist: hypothesis; extra == 'all'
16
+ Requires-Dist: mypy; extra == 'all'
17
+ Requires-Dist: pip-api; extra == 'all'
18
+ Requires-Dist: pytest; extra == 'all'
19
+ Requires-Dist: pytest-asyncio; extra == 'all'
20
+ Requires-Dist: pytest-cov; extra == 'all'
21
+ Requires-Dist: pytest-mock; extra == 'all'
22
+ Requires-Dist: ruff; extra == 'all'
23
+ Provides-Extra: dev
24
+ Requires-Dist: hatch; extra == 'dev'
25
+ Requires-Dist: mypy; extra == 'dev'
26
+ Requires-Dist: pip-api; extra == 'dev'
27
+ Requires-Dist: ruff; extra == 'dev'
28
+ Provides-Extra: lint
29
+ Requires-Dist: mypy; extra == 'lint'
30
+ Requires-Dist: ruff; extra == 'lint'
31
+ Provides-Extra: mcp
32
+ Requires-Dist: fastmcp; extra == 'mcp'
33
+ Provides-Extra: test
34
+ Requires-Dist: hypothesis; extra == 'test'
35
+ Requires-Dist: pytest; extra == 'test'
36
+ Requires-Dist: pytest-asyncio; extra == 'test'
37
+ Requires-Dist: pytest-cov; extra == 'test'
38
+ Requires-Dist: pytest-mock; extra == 'test'
39
+ Description-Content-Type: text/markdown
40
+
41
+ # mcp-server-nmap
42
+
43
+ MCP server that exposes the python-nmap library as MCP tools for network scanning operations.
44
+
45
+ [![PyPI](https://img.shields.io/pypi/v/mcp-server-nmap.svg)](https://pypi.org/project/mcp-server-nmap/)
46
+ [![Python](https://img.shields.io/pypi/pyversions/mcp-server-nmap.svg)](https://pypi.org/project/mcp-server-nmap/)
47
+
48
+ ## What is this?
49
+
50
+ This MCP server wraps the python-nmap library, allowing AI assistants to perform network reconnaissance through MCP tools. It provides three scanning interfaces:
51
+
52
+ 1. **PortScanner** (synchronous) - Blocking scans that wait for completion
53
+ 2. **PortScannerAsync** (asynchronous) - Non-blocking scans with callbacks
54
+ 3. **PortScannerYield** (generator) - Streaming results as hosts are discovered
55
+
56
+ ## Prerequisites
57
+
58
+ - [nmap](https://nmap.org/) must be installed on the system
59
+ - Python 3.10+
60
+
61
+ ## Install
62
+
63
+ ```bash
64
+ pip install mcp-server-nmap
65
+ ```
66
+
67
+ ## MCP Server Registration
68
+
69
+ Add this to your MCP settings file:
70
+
71
+ ```json
72
+ {
73
+ "mcpServers": {
74
+ "mcp-server-nmap": {
75
+ "command": "mcp-server-nmap"
76
+ }
77
+ }
78
+ }
79
+ ```
80
+
81
+ Or with custom nmap path:
82
+
83
+ ```json
84
+ {
85
+ "mcpServers": {
86
+ "mcp-server-nmap": {
87
+ "command": "mcp-server-nmap",
88
+ "env": {
89
+ "PATH": "/custom/path:$PATH"
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ## Available Tools
97
+
98
+ ### Initialization
99
+
100
+ | Tool | Description |
101
+ |------|-------------|
102
+ | `port_scanner_init` | Initialize synchronous PortScanner |
103
+ | `port_scanner_async_init` | Initialize async PortScannerAsync |
104
+ | `port_scanner_yield_init` | Initialize generator-based PortScannerYield |
105
+
106
+ ### Scanning
107
+
108
+ | Tool | Description |
109
+ |------|-------------|
110
+ | `port_scanner_scan` | Scan hosts with nmap (synchronous) |
111
+ | `port_scanner_async_scan` | Scan hosts (async, non-blocking) |
112
+ | `port_scanner_yield_scan` | Scan with streaming results |
113
+ | `port_scanner_listscan` | List hosts without scanning |
114
+
115
+ ### Results & State
116
+
117
+ | Tool | Description |
118
+ |------|-------------|
119
+ | `port_scanner_all_hosts` | Get all scanned hosts |
120
+ | `port_scanner_has_host` | Check if host was scanned |
121
+ | `port_scanner_get_item` | Get detailed host scan data |
122
+ | `port_scanner_scaninfo` | Get scan configuration info |
123
+ | `port_scanner_scanstats` | Get scan statistics |
124
+ | `port_scanner_command_line` | Get nmap command used |
125
+ | `port_scanner_csv` | Get CSV output |
126
+ | `port_scanner_last_output` | Get raw nmap text output |
127
+
128
+ ### Async Control
129
+
130
+ | Tool | Description |
131
+ |------|-------------|
132
+ | `port_scanner_async_still_scanning` | Check if scan in progress |
133
+ | `port_scanner_async_stop` | Stop running scan |
134
+ | `port_scanner_async_wait` | Wait for scan to complete |
135
+
136
+ ### XML Parsing
137
+
138
+ | Tool | Description |
139
+ |------|-------------|
140
+ | `port_scanner_analyse_xml` | Parse existing nmap XML output |
141
+
142
+ ## Common Scan Workflows
143
+
144
+ ### Basic port scan
145
+
146
+ ```python
147
+ # Initialize scanner
148
+ port_scanner_init()
149
+
150
+ # Scan target
151
+ port_scanner_scan(hosts="192.168.1.1", ports="22,80,443", arguments="-sV")
152
+
153
+ # Get results
154
+ port_scanner_get_item(host="192.168.1.1")
155
+ ```
156
+
157
+ ### Service version detection
158
+
159
+ ```python
160
+ port_scanner_scan(hosts="scanme.nmap.org", arguments="-sV -sC")
161
+ ```
162
+
163
+ ### Scan multiple hosts
164
+
165
+ ```python
166
+ port_scanner_scan(hosts="192.168.1.1-254", arguments="-sS -p 22")
167
+ port_scanner_all_hosts()
168
+ ```
169
+
170
+ ### Network sweep
171
+
172
+ ```python
173
+ port_scanner_scan(hosts="192.168.1.0/24", arguments="-sn")
174
+ port_scanner_csv() # Export to CSV
175
+ ```
176
+
177
+ ## nmap Arguments Reference
178
+
179
+ | Argument | Description |
180
+ |----------|-------------|
181
+ | `-sn` | Ping scan (host discovery) |
182
+ | `-sS` | TCP SYN scan |
183
+ | `-sT` | TCP connect scan |
184
+ | `-sU` | UDP scan |
185
+ | `-sV` | Service version detection |
186
+ | `-sC` | Default scripts |
187
+ | `-O` | OS detection |
188
+ | `-p` | Port range |
189
+ | `-oA` | Output all formats |
190
+
191
+ ## Development
192
+
193
+ ```bash
194
+ git clone https://github.com/daedalus/mcp-server-nmap.git
195
+ cd mcp-server-nmap
196
+ pip install -e ".[test]"
197
+
198
+ # run tests
199
+ pytest
200
+
201
+ # format
202
+ ruff format src/ tests/
203
+
204
+ # lint
205
+ ruff check src/ tests/
206
+
207
+ # type check
208
+ mypy src/
209
+ ```
mcp_server_nmap-0.1.0/README.md ADDED
@@ -0,0 +1,169 @@
1
+ # mcp-server-nmap
2
+
3
+ MCP server that exposes the python-nmap library as MCP tools for network scanning operations.
4
+
5
+ [![PyPI](https://img.shields.io/pypi/v/mcp-server-nmap.svg)](https://pypi.org/project/mcp-server-nmap/)
6
+ [![Python](https://img.shields.io/pypi/pyversions/mcp-server-nmap.svg)](https://pypi.org/project/mcp-server-nmap/)
7
+
8
+ ## What is this?
9
+
10
+ This MCP server wraps the python-nmap library, allowing AI assistants to perform network reconnaissance through MCP tools. It provides three scanning interfaces:
11
+
12
+ 1. **PortScanner** (synchronous) - Blocking scans that wait for completion
13
+ 2. **PortScannerAsync** (asynchronous) - Non-blocking scans with callbacks
14
+ 3. **PortScannerYield** (generator) - Streaming results as hosts are discovered
15
+
16
+ ## Prerequisites
17
+
18
+ - [nmap](https://nmap.org/) must be installed on the system
19
+ - Python 3.10+
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ pip install mcp-server-nmap
25
+ ```
26
+
27
+ ## MCP Server Registration
28
+
29
+ Add this to your MCP settings file:
30
+
31
+ ```json
32
+ {
33
+ "mcpServers": {
34
+ "mcp-server-nmap": {
35
+ "command": "mcp-server-nmap"
36
+ }
37
+ }
38
+ }
39
+ ```
40
+
41
+ Or with custom nmap path:
42
+
43
+ ```json
44
+ {
45
+ "mcpServers": {
46
+ "mcp-server-nmap": {
47
+ "command": "mcp-server-nmap",
48
+ "env": {
49
+ "PATH": "/custom/path:$PATH"
50
+ }
51
+ }
52
+ }
53
+ }
54
+ ```
55
+
56
+ ## Available Tools
57
+
58
+ ### Initialization
59
+
60
+ | Tool | Description |
61
+ |------|-------------|
62
+ | `port_scanner_init` | Initialize synchronous PortScanner |
63
+ | `port_scanner_async_init` | Initialize async PortScannerAsync |
64
+ | `port_scanner_yield_init` | Initialize generator-based PortScannerYield |
65
+
66
+ ### Scanning
67
+
68
+ | Tool | Description |
69
+ |------|-------------|
70
+ | `port_scanner_scan` | Scan hosts with nmap (synchronous) |
71
+ | `port_scanner_async_scan` | Scan hosts (async, non-blocking) |
72
+ | `port_scanner_yield_scan` | Scan with streaming results |
73
+ | `port_scanner_listscan` | List hosts without scanning |
74
+
75
+ ### Results & State
76
+
77
+ | Tool | Description |
78
+ |------|-------------|
79
+ | `port_scanner_all_hosts` | Get all scanned hosts |
80
+ | `port_scanner_has_host` | Check if host was scanned |
81
+ | `port_scanner_get_item` | Get detailed host scan data |
82
+ | `port_scanner_scaninfo` | Get scan configuration info |
83
+ | `port_scanner_scanstats` | Get scan statistics |
84
+ | `port_scanner_command_line` | Get nmap command used |
85
+ | `port_scanner_csv` | Get CSV output |
86
+ | `port_scanner_last_output` | Get raw nmap text output |
87
+
88
+ ### Async Control
89
+
90
+ | Tool | Description |
91
+ |------|-------------|
92
+ | `port_scanner_async_still_scanning` | Check if scan in progress |
93
+ | `port_scanner_async_stop` | Stop running scan |
94
+ | `port_scanner_async_wait` | Wait for scan to complete |
95
+
96
+ ### XML Parsing
97
+
98
+ | Tool | Description |
99
+ |------|-------------|
100
+ | `port_scanner_analyse_xml` | Parse existing nmap XML output |
101
+
102
+ ## Common Scan Workflows
103
+
104
+ ### Basic port scan
105
+
106
+ ```python
107
+ # Initialize scanner
108
+ port_scanner_init()
109
+
110
+ # Scan target
111
+ port_scanner_scan(hosts="192.168.1.1", ports="22,80,443", arguments="-sV")
112
+
113
+ # Get results
114
+ port_scanner_get_item(host="192.168.1.1")
115
+ ```
116
+
117
+ ### Service version detection
118
+
119
+ ```python
120
+ port_scanner_scan(hosts="scanme.nmap.org", arguments="-sV -sC")
121
+ ```
122
+
123
+ ### Scan multiple hosts
124
+
125
+ ```python
126
+ port_scanner_scan(hosts="192.168.1.1-254", arguments="-sS -p 22")
127
+ port_scanner_all_hosts()
128
+ ```
129
+
130
+ ### Network sweep
131
+
132
+ ```python
133
+ port_scanner_scan(hosts="192.168.1.0/24", arguments="-sn")
134
+ port_scanner_csv() # Export to CSV
135
+ ```
136
+
137
+ ## nmap Arguments Reference
138
+
139
+ | Argument | Description |
140
+ |----------|-------------|
141
+ | `-sn` | Ping scan (host discovery) |
142
+ | `-sS` | TCP SYN scan |
143
+ | `-sT` | TCP connect scan |
144
+ | `-sU` | UDP scan |
145
+ | `-sV` | Service version detection |
146
+ | `-sC` | Default scripts |
147
+ | `-O` | OS detection |
148
+ | `-p` | Port range |
149
+ | `-oA` | Output all formats |
150
+
151
+ ## Development
152
+
153
+ ```bash
154
+ git clone https://github.com/daedalus/mcp-server-nmap.git
155
+ cd mcp-server-nmap
156
+ pip install -e ".[test]"
157
+
158
+ # run tests
159
+ pytest
160
+
161
+ # format
162
+ ruff format src/ tests/
163
+
164
+ # lint
165
+ ruff check src/ tests/
166
+
167
+ # type check
168
+ mypy src/
169
+ ```
mcp_server_nmap-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,94 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "mcp-server-nmap"
7
+ version = "0.1.0"
8
+ description = "MCP server for python-nmap network scanning"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = {text = "MIT"}
12
+ authors = [
13
+ {name = "Dario Clavijo", email = "clavijodario@gmail.com"}
14
+ ]
15
+ dependencies = [
16
+ "python-nmap==0.7.1",
17
+ ]
18
+
19
+ [project.optional-dependencies]
20
+ mcp = ["fastmcp"]
21
+ dev = [
22
+ "ruff",
23
+ "mypy",
24
+ "hatch",
25
+ "pip-api",
26
+ ]
27
+ test = [
28
+ "pytest",
29
+ "pytest-cov",
30
+ "pytest-mock",
31
+ "pytest-asyncio",
32
+ "hypothesis",
33
+ ]
34
+ lint = [
35
+ "ruff",
36
+ "mypy",
37
+ ]
38
+ all = ["mcp-server-nmap[dev,test,lint]"]
39
+
40
+ [project.scripts]
41
+ mcp-server-nmap = "mcp_server_nmap.__main__:main"
42
+
43
+ [project.urls]
44
+ Homepage = "https://github.com/daedalus/mcp-server-nmap"
45
+ Repository = "https://github.com/daedalus/mcp-server-nmap"
46
+ Issues = "https://github.com/daedalus/mcp-server-nmap/issues"
47
+
48
+ [tool.hatch.build.targets.wheel]
49
+ packages = ["src/mcp_server_nmap"]
50
+
51
+ [tool.hatch.build.targets.sdist]
52
+ include = ["src/mcp_nmap"]
53
+
54
+ [tool.ruff]
55
+ line-length = 88
56
+ target-version = "py311"
57
+
58
+ [tool.ruff.lint]
59
+ select = ["E", "F", "W", "I", "UP", "ANN", "TCH", "N", "C4", "ARG"]
60
+ ignore = ["E501"]
61
+
62
+ [tool.ruff.lint.per-file-ignores]
63
+ "__init__.py" = ["F401"]
64
+ "tests/*" = ["ANN", "ARG"]
65
+
66
+ [tool.ruff.lint.pydocstyle]
67
+ convention = "google"
68
+
69
+ [tool.mypy]
70
+ python_version = "3.11"
71
+ strict = true
72
+ warn_return_any = true
73
+ warn_unused_ignores = true
74
+ ignore_missing_imports = true
75
+
76
+ [tool.pytest.ini_options]
77
+ testpaths = ["tests"]
78
+ addopts = "-v --tb=short --cov=src --cov-fail-under=80"
79
+ filterwarnings = ["ignore::DeprecationWarning"]
80
+
81
+ [tool.coverage.run]
82
+ source = ["src"]
83
+ branch = true
84
+
85
+ [tool.coverage.report]
86
+ exclude = ["tests/*", "*/__init__.py"]
87
+ exclude_lines = [
88
+ "pragma: no cover",
89
+ "def __repr__",
90
+ "raise AssertionError",
91
+ "raise NotImplementedError",
92
+ "if __name__ == .__main__.:",
93
+ "if TYPE_CHECKING:",
94
+ ]