mcp-connect— Kali Agent MCP v2

A Codex-style, structured MCP toolbox for operating a Kali Linux machine from ChatGPT or any compatible MCP client.

This repository contains the complete Kali Agent MCP v2.1.0 server developed in ~/mcp-connect, with 126 MCP tools for shell execution, persistent terminal sessions, filesystem operations, reversible patches, durable jobs, Git/worktrees, project build and test workflows, repository intelligence, Docker, Chromium browser automation, artifacts, checkpoints, system services, sandboxing, auditing, and Kali security-tool wrappers.

Security warning: this project intentionally exposes powerful machine-control capabilities. Run it only on systems you own or are authorized to administer, use a dedicated non-root account, keep the MCP server private, and never commit runtime keys, API tokens, private keys, .env files, tunnel profiles containing secrets, or runtime state.

Project status

• Server version: 2.1.0
• MCP tool discovery: 126 tools
• MCP stdio protocol: validated
• Integration suite: 19 tests passed on the source machine
• Explicit execution timing policy: supported on process-oriented tools
• Persistent tmux sessions: supported
• Durable background jobs and incremental logs: supported
• Git branches/worktrees and reversible patches: supported
• Docker, Chromium/Playwright, bubblewrap sandbox, systemd inspection/actions: supported
• OpenAI Secure MCP Tunnel integration: included

Architecture

ChatGPT / MCP client
        |
        |  OpenAI Secure MCP Tunnel or another private MCP transport
        v
   tunnel-client
        |
        |  stdio MCP
        v
  bin/kali-agent-mcp
        |
        v
  Kali Agent MCP v2.1
        |
        +-- system / health / environment / policy
        +-- filesystem / grep / patches / patch rollback
        +-- one-shot shell / persistent tmux PTY / interrupts
        +-- durable jobs / status / logs / wait / cancel
        +-- process / port / service inspection
        +-- Git / diff / branches / worktrees / blame
        +-- build / test / lint / typecheck / benchmark
        +-- repository map / symbols / dependencies / instructions
        +-- Docker / Compose
        +-- Chromium + Playwright browser sessions
        +-- checkpoints / tasks / artifacts / agent workspaces
        +-- bubblewrap sandbox
        `-- nmap / nikto / gobuster / dirb / sqlmap / Metasploit /
            Hydra / John / WPScan / enum4linux wrappers

The preferred tunnel design does not require a public listener. tunnel-client runs on the Kali machine and starts this MCP server as a local stdio child process.

Requirements

Minimum:

• Kali Linux or another compatible Linux distribution
• Python 3.11+
• python3-venv
• Git

Recommended for all features:

• Chromium
• Node.js + npm
• tmux
• Docker
• bubblewrap (bwrap)
• ripgrep (rg)
• standard Kali security tools used by the wrappers

The Python package dependencies are declared in pyproject.toml:

mcp >=1.22,<2
pydantic >=2.0
psutil >=5.9
GitPython >=3.1
playwright >=1.40        # optional browser extra
pytest >=8               # development/test extra

Fast local setup

git clone https://github.com/asarlashmit/MCP-Connect.git ~/mcp-connect
cd ~/mcp-connect

chmod +x scripts/*.sh bin/* install-kali-chatgpt-mcp.sh rotate-runtime-key.sh
./scripts/setup-local.sh
./scripts/full-validate.sh

The setup script:

1. creates .venv/;
2. installs the project in editable mode with development and browser extras;
3. installs the project-local matching Playwright Node driver when Node/npm are present;
4. symlinks kali-agent and kali-agent-mcp into ~/.local/bin;
5. leaves all credentials and persistent state outside Git.

Basic checks:

cd ~/mcp-connect
./bin/kali-agent health
./bin/kali-agent capabilities
./bin/kali-agent tools
./scripts/doctor.sh

Local MCP server entry point:

~/mcp-connect/bin/kali-agent-mcp

Connect it to ChatGPT through OpenAI Secure MCP Tunnel

The full end-to-end replication guide is in docs/INSTALLATION.md.

At a high level:

1. Clone and validate this repository.

2. Create an OpenAI MCP tunnel and a separate runtime API key with the required tunnel permissions.

3. Install the official tunnel-client.

4. Initialize a named stdio tunnel profile whose MCP command is:

   /home/<your-user>/mcp-connect/bin/kali-agent-mcp
   

5. Keep the runtime key in a mode-600 environment file outside the repository.

6. Run tunnel-client doctor --profile <profile> --explain.

7. Run the tunnel persistently, preferably through systemd.

8. In ChatGPT, create a developer-mode app/plugin, choose Connection: Tunnel, and select the tunnel.

9. Verify with server_health and a harmless timed exec_command call.

This repository also preserves the original full installer used during development:

./install-kali-chatgpt-mcp.sh

That installer provisions the official Kali mcp-kali-server bridge, downloads the latest official OpenAI tunnel-client, configures the tunnel service, stores the runtime key outside the repository, and performs security checks. Afterward, scripts/activate-tunnel.sh switches the tunnel profile to the 126-tool v2 server:

./scripts/activate-tunnel.sh "$HOME/.config/tunnel-client/kali-chatgpt.yaml"
sudo systemctl restart openai-kali-mcp-tunnel.service

The detailed guide explains both the direct v2 stdio route and the historical two-stage route used to build this machine.

ChatGPT test prompt

After the tunnel and app are connected, a safe first prompt is:

Use my Kali MCP app.
First call server_health.
Then count the available tools.
Verify that exec_command exposes:
- expected_runtime_seconds
- timeout_seconds
- check_after_seconds
- poll_interval_seconds
- on_timeout
Then run a harmless command such as `printf 'mcp-ok\n' && uname -s` with explicitly selected timing values.
Do not modify the system.

Explicit execution timing policy

Process-oriented tools expose these controls:

expected_runtime_seconds
timeout_seconds
check_after_seconds
poll_interval_seconds
on_timeout = kill | return_partial | continue_background

Example:

{
  "command": "npm run build",
  "cwd": "/home/kali/project",
  "expected_runtime_seconds": 120,
  "timeout_seconds": 300,
  "check_after_seconds": 30,
  "poll_interval_seconds": 5,
  "on_timeout": "continue_background"
}

When on_timeout is continue_background, long-running work can return a durable job_id for later job_status, job_logs, or job_wait calls instead of forcing one MCP call to remain open indefinitely.

See docs/EXECUTION_POLICY.md.

Tool families

The 126 tools include:

Family	Examples
System	server_health, server_capabilities, system_info, environment_info
Filesystem	read/write/append/copy/move/delete/mkdir/stat/list/find/grep
Patch workflow	apply_patch, patch_history, revert_patch
Shell and PTY	exec_command, persistent tmux sessions, capture, interrupt
Jobs	start/status/logs/wait/cancel/list/cleanup
Processes and ports	list/info/tree/kill, port inventory and owner lookup
Git	status/diff/log/show/branches/checkout/add/reset/commit/restore/blame/worktrees
Development	detect/install/build/test/lint/typecheck/benchmark
Repository intelligence	tree/map/summary/frameworks/entrypoints/tests/instructions/TODOs/dependencies/symbols
Docker	ps/inspect/logs/exec/build/run/stop/remove/compose
Browser	open/navigate/text/html/screenshot/console/network/close/list
State	checkpoints/tasks/agent workspaces
Artifacts	register/create/list/info/read/delete
Services	status/logs/list/actions
Policy and sandbox	policy status/path checks/classification/sandbox/audit
Kali wrappers	nmap, nikto, gobuster, dirb, sqlmap, Metasploit, Hydra, John, WPScan, enum4linux

For the generated complete catalog, see docs/TOOL_CATALOG.md.

Repository layout

mcp-connect/
├── bin/
│   ├── kali-agent
│   └── kali-agent-mcp
├── config/
│   └── kali-agent-mcp.example.json
├── docs/
│   ├── INSTALLATION.md
│   ├── ARCHITECTURE.md
│   ├── EXECUTION_POLICY.md
│   ├── OPERATIONS.md
│   ├── SECURITY_MODEL.md
│   ├── TOOL_CATALOG.md
│   ├── TEST_REPORT.md
│   └── TUNNEL_SETUP.md
├── kali_agent_mcp/
│   ├── core/
│   ├── tools/
│   ├── cli.py
│   └── server.py
├── scripts/
│   ├── setup-local.sh
│   ├── activate-tunnel.sh
│   ├── doctor.sh
│   ├── full-validate.sh
│   ├── install-browser-driver.sh
│   └── verify_all_126.py
├── systemd/
├── tests/
├── install-kali-chatgpt-mcp.sh
├── rotate-runtime-key.sh
├── pyproject.toml
└── README.md

Configuration

Copy the example only when you need custom policy settings:

cp config/kali-agent-mcp.example.json ~/.config/kali-agent-mcp/config.json
chmod 600 ~/.config/kali-agent-mcp/config.json

Default policy values include:

{
  "command_timeout": 180,
  "max_output_bytes": 200000,
  "shell_enabled": true,
  "browser_enabled": true,
  "security_tools_enabled": true,
  "audit_enabled": true,
  "allowed_roots": ["/home/kali", "/tmp"],
  "default_cwd": "/home/kali"
}

Adjust paths for your own username and trust boundary. A public repository should never contain your live config if it contains machine-specific secrets or credentials.

Runtime state

Persistent runtime state is stored outside the repository under:

~/.local/state/kali-agent-mcp/
├── artifacts/
├── audit.jsonl
├── backups/
├── browser/
├── checkpoints/
├── jobs/
├── patches/
├── sessions/
└── tasks/

Do not commit this directory.

Credential handling

The public repository is designed so that credentials remain outside Git:

• runtime API keys: external mode-600 environment file;
• tunnel profiles: local machine configuration;
• GitHub credentials: use gh auth, SSH agent, or your normal Git credential helper;
• .env, private-key, certificate, runtime, cache, log, verification-run, and browser dependency directories: ignored or excluded;
• audit records: likely credentials are redacted by the server.

Before publishing a fork, run the secret-scan procedure in SECURITY.md.

Browser support

Browser tools use the installed Chromium binary at /usr/bin/chromium. The Python Playwright package may need a matching Node driver, so the repository installs a project-local driver under the ignored path:

.runtime/playwright-node/

Install or refresh it with:

./scripts/install-browser-driver.sh

No browser binary is committed to this repository.

Validation

Run:

./scripts/full-validate.sh

The validation pipeline compiles the Python source, runs the doctor checks, executes pytest, verifies tool-name uniqueness, and reports the discovered tool count.

For the more exhaustive integration verifier:

./scripts/verify_all_126.py

Some security-tool verification cases intentionally use loopback-only local test targets. Do not point security tools at systems you do not own or lack explicit permission to test.

Documentation

• docs/INSTALLATION.md — full clone-to-ChatGPT replication guide.
• docs/ARCHITECTURE.md — architecture and runtime design.
• docs/EXECUTION_POLICY.md — explicit runtime/timeout/polling/background semantics.
• docs/TOOL_CATALOG.md — generated catalog of all tools.
• docs/SECURITY_MODEL.md — trust boundaries, path policy, auditing, and limitations.
• docs/OPERATIONS.md — operational commands and troubleshooting.
• docs/TEST_REPORT.md — validation summary.
• docs/TUNNEL_SETUP.md — historical secure-tunnel installer documentation.
• SECURITY.md — secret hygiene and vulnerability reporting guidance.

Official references

• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
• Kali mcp-kali-server: https://www.kali.org/tools/mcp-kali-server/
• Model Context Protocol: https://modelcontextprotocol.io/

Responsible use

This project can execute commands and invoke offensive-security tools. Use it only on infrastructure you own or have explicit authorization to test. The maintainers and contributors are not responsible for misuse.

License

MIT License. See LICENSE.