Content
# host-mcp
`host-mcp` is a standalone MCP (Model Context Protocol) server that provides authorized file access and command execution capabilities to AI Agents like Claw and MiClaw through Streamable HTTP. It does not rely on Python or Node.js runtime environments.
Supported:
- Termux / Android
- Standard Linux
- WSL
Not supported on macOS and native Windows.
> Initially designed for MiClaw to use Termux, with other environments adapted for convenience. All code generated by ChatGPT. Review code, configuration, and permission policies before use, and run only in trusted environments.
## Main Features
- Read, search, and manage files in authorized folders.
- Run controlled commands through `exec_run` that are pre-approved by the device owner.
- Run arbitrary Shell commands through `shell_run` with explicit enablement.
- Explain command status and enablement to MCP clients via `command_status`.
- Protect Streamable HTTP MCP interface with Bearer Token.
- Support Termux runit and Linux/WSL systemd user background services.
"Authorized folders" are referred to as **Root** in the configuration. It does not imply Android root or superuser privileges but rather directories that allow access by built-in file tools.
## Security Defaults
- Listen on `127.0.0.1:8765` by default, with MCP address `http://127.0.0.1:8765/mcp`.
- Each request requires a Bearer Token generated during initialization.
- Linux/WSL do not authorize any folders by default; Termux HOME is readable by default, with prefix and shared storage mounted as read-only for built-in file tools.
- `exec_run` and `shell_run` do not execute commands by default, but tools are visible and return setup prompts.
- Trusted Shell is not a sandbox and can bypass authorization folder and built-in file tool read-only policies.
- Do not expose plain HTTP, non-loopback listeners, and trusted Shell to the public internet or untrusted networks.
Read the full boundary in: [Security Model](docs/SECURITY.md) and [Permission Policy](docs/POLICY.md).
## Quick Start
### 1. Initialization
```sh
host-mcp init
```
Confirm, and the program will display the newly generated Token, MCP address, and startup command for the current profile. The Token is like a password; copy it to the MCP client and do not commit it to Git or public logs.
View or rotate the Token later:
```sh
host-mcp token show
host-mcp token rotate
```
### 2. Start Service
Choose one startup method; do not run foreground and background instances simultaneously.
Run in Termux background:
```sh
host-mcp service enable
host-mcp service status
```
Run in Linux/WSL background:
```sh
host-mcp service install
host-mcp service enable
host-mcp service start
host-mcp service status
```
Debug in foreground:
```sh
host-mcp serve
```
Check status:
```sh
host-mcp status
```
### 3. Configure MCP Client
```json
{
"mcpServers": {
"host-mcp": {
"type": "streamable-http",
"url": "http://127.0.0.1:8765/mcp",
"headers": {
"Authorization": "Bearer <TOKEN>"
}
}
}
}
```
Replace `<TOKEN>` with the full output of `host-mcp token show`.
If the client is on a different device, configure a trusted LAN listener and change the URL to the host's LAN address. See: [Network Listener and MCP Client Configuration](docs/USAGE.md#network-listener-and-mcp-client-configuration).
## Let Claw Execute Commands
### Controlled Commands (Recommended)
`exec_run` can only execute fixed rules pre-approved locally, without Shell:
```sh
host-mcp commands status
host-mcp commands presets
host-mcp commands setup
```
Enable fixed Git status query:
```sh
host-mcp commands enable git-status --folder termux-home:. --yes
host-mcp service restart
```
### Trusted Shell (High Risk)
If you need to execute arbitrary terminal commands like `pkg install`, `python xxx.py`, `mkdir ~/workdir`:
```sh
host-mcp shell enable
host-mcp service restart
```
Enabling requires reading risk descriptions and typing the full confirmation text. Trusted Shell has system privileges of the `host-mcp` run account, can access the network, start subprocesses, and modify Termux prefix; it is not constrained by Root file boundaries and does not prompt locally for each command.
After MCP client initialization, call the protocol's `tools/list` and strictly follow the returned tool names and `inputSchema`; do not guess `help`, `lscmd`, or parameter formats. With Trusted Shell enabled, the shortest call can be:
```json
{ "command": "ip addr; ip route" }
```
The service uses the default starting directory in the configuration. When specifying a directory, `cwd` must be an object, not a string, and do not put `root` at the top:
```json
{
"command": "python script.py",
"cwd": { "root": "termux-home", "path": "work" }
}
```
`ifconfig` may not be installed in Termux; check network information by trying `ifconfig` first and supplementing with `ip addr; ip route`. Different Android/Termux combinations may restrict certain `/proc` or netlink network information; if command output is permission-restricted, report the restriction truthfully. New Trusted Shell adds `/system/bin` to its Termux command search path. See more error handling examples in: [Command Execution Guide](docs/USAGE.md#command-execution).
Disable:
```sh
host-mcp shell disable
host-mcp service restart
```
Differences and complete examples of `exec_run`, `shell_run`, `command_status` are in: [Command Execution Guide](docs/USAGE.md#command-execution).
## Build
Requires Go 1.26.5 or compatible newer version:
```sh
git clone https://github.com/thiasap/host-mcp.git
cd host-mcp
go build -trimpath -o host-mcp ./cmd/host-mcp
```
Complete build, test, release, and verification are in: [Complete Usage Guide](docs/USAGE.md).
## Documentation
- [Complete Usage and Configuration Guide](docs/USAGE.md): Initialization, Profile, Service, Client, LAN, Commands, File Permissions, Diagnostics, and Release Artifacts.
- [Permission Policy](docs/POLICY.md): Root, Grant, Termux read-only, and command capability rules.
- [Security Model](docs/SECURITY.md): Authentication, Network, File Boundaries, Trusted Shell, and Threat Model.
