IMALI Commander

Give AI assistants (Claude Desktop, ChatGPT and any MCP client) safe access to one folder on your computer or server: read, write, upload, download, search, and check git status. Nothing outside that folder, no shell.

• Scoped to a single workspace folder; symlink and ../ escapes are blocked

• Works locally over stdio, or remotely over authenticated HTTPS

• Read-only mode for "look but don't touch"

• Audit log of every action (never file contents or tokens)

• Token stored only as a hash; brute-force lockout

• One command to run as a background service on macOS or Linux

Free and Pro

Activate Pro with imali-commander activate <license-key>, then restart. The license is checked at most once a day; if you're offline, Pro keeps working for 7 days from the last successful check. Free never contacts the internet.

Related MCP server: MCPort

Install

Requires Node.js 20+.

npm install -g github:IMALI-DEFI/imali-commander
imali-commander init --workspace ~/imali-workspace

init prints your access token once plus a ready-to-paste client config.

Connect a desktop client (stdio)

Paste the JSON that init printed into your client's MCP config, e.g. Claude Desktop → Settings → Developer → Edit Config, then restart the client. Without a global install you can also run it through npx:

{
  "mcpServers": {
    "imali-commander": { "command": "npx", "args": ["-y", "github:IMALI-DEFI/imali-commander", "start"] }
  }
}

The config init prints looks like:

{
  "mcpServers": {
    "imali-commander": { "command": "/usr/local/bin/node", "args": ["/…/imali-commander/src/server.js"] }
  }
}

Run over HTTP

imali-commander start --http                 # foreground, http://127.0.0.1:8787/mcp
imali-commander service install --load       # background service that starts at login

Clients send Authorization: Bearer <token>. Commander only listens on localhost; for access from other machines put it behind HTTPS (next section).

Remote access over HTTPS

Remote access is a Pro feature.

Docker (recommended): Commander plus Caddy with automatic Let's Encrypt certificates.

cp deploy/.env.example deploy/.env     # set DOMAIN, IMALI_MCP_TOKEN_SHA256 and IMALI_LICENSE_KEY
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d

Endpoint: https://<DOMAIN>/mcp. Only /mcp and /health are exposed.

Without Docker: run Commander as a service, set "trustProxy": true in the config, and use deploy/Caddyfile.host with Caddy on the same machine.

Commands

Tools

device_info, list_files, read_file, write_file, download_file, upload_file, create_directory, file_info, search_files, run_workspace_command (pwd, ls, git-status, git-diff, git-log only). Read-only mode removes write_file, upload_file and create_directory.

Limits: text files 1 MB, transfers 5 MB, HTTP body 8 MB, commands 5 s / 32 KB output.

Configuration

~/.imali-commander/config.json (created by init, mode 600). Environment variables override it; change the config folder with IMALI_HOME.

Troubleshooting

• Client shows no tools: run imali-commander doctor, then restart the client.

• 401 Unauthorized: wrong token. Run imali-commander rotate-token, then service restart.

• 429 Too many requests: 10 bad tokens within a minute locks that address out for the rest of the minute.

• Service logs: ~/.imali-commander/logs/service.log.

See SECURITY.md for the security model and CHANGELOG.md for releases.