# 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

```text
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`:

```text
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

```bash
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:

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

Local MCP server entry point:

```bash
~/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`](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:

   ```text
   /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:

```bash
./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:

```bash
./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:

```text
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:

```text
expected_runtime_seconds
timeout_seconds
check_after_seconds
poll_interval_seconds
on_timeout = kill | return_partial | continue_background
```

Example:

```json
{
  "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`](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`](docs/TOOL_CATALOG.md).

## Repository layout

```text
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:

```bash
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:

```json
{
  "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:

```text
~/.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`](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:

```text
.runtime/playwright-node/
```

Install or refresh it with:

```bash
./scripts/install-browser-driver.sh
```

No browser binary is committed to this repository.

## Validation

Run:

```bash
./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:

```bash
./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`](docs/INSTALLATION.md) — full clone-to-ChatGPT replication guide.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture and runtime design.
- [`docs/EXECUTION_POLICY.md`](docs/EXECUTION_POLICY.md) — explicit runtime/timeout/polling/background semantics.
- [`docs/TOOL_CATALOG.md`](docs/TOOL_CATALOG.md) — generated catalog of all tools.
- [`docs/SECURITY_MODEL.md`](docs/SECURITY_MODEL.md) — trust boundaries, path policy, auditing, and limitations.
- [`docs/OPERATIONS.md`](docs/OPERATIONS.md) — operational commands and troubleshooting.
- [`docs/TEST_REPORT.md`](docs/TEST_REPORT.md) — validation summary.
- [`docs/TUNNEL_SETUP.md`](docs/TUNNEL_SETUP.md) — historical secure-tunnel installer documentation.
- [`SECURITY.md`](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`](LICENSE).