Chatbottool MCP

Give AI useful tools—not the keys to your machine.

A local-first MCP workspace bridge with guarded files, controlled execution, recoverable changes, and a deliberately narrow trust boundary.

The idea

Local agents are useful because they can touch real files, run real tests, and make real changes. That is also exactly what makes a careless bridge dangerous.

Chatbottool MCP puts a small, inspectable capability layer between the client and the workspace.

Related MCP server: Code MCP Server

How it works

The client never receives ambient authority. It sees only the tools exposed by the selected mode, and each tool still passes through path, process, network, secret, and workspace checks.

Two practical surfaces

Full mode adds full shell, recoverable deletion, background processes, repository initialization and branch recovery, Python module execution, direct file placement, and allowlisted network fetch.

Tool visibility and shell policy are independent. For a trusted client that needs git clone and package installation while retaining the guarded destructive-command patterns, use bashMode: "install". The configurable commandPath exposes the intended Node/npm/Git installation to child commands. See Installer mode and the installer profile example.

The public edition deliberately contains no browser automation, desktop control, computer-use bridge, private service integration, or Git push tool.

Quick start

Requires Node.js 22.19+ (below Node 27), Git, and macOS or Linux.

git clone https://github.com/tamvi-journal/chatbottool-mcp.git
cd chatbottool-mcp
npm install
npm run build
node dist/cli.js init

The initializer creates a local policy file and a private owner password under ~/.chatbottool-mcp/.

Local MCP clients

node /absolute/path/to/chatbottool-mcp/dist/cli.js serve-stdio

{
  "mcpServers": {
    "chatbottool-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/chatbottool-mcp/dist/cli.js", "serve-stdio"]
    }
  }
}

HTTP + OAuth

node dist/cli.js serve

The server binds to localhost by default and exposes /mcp, /healthz, and a small status dashboard. Remote clients need a public HTTPS origin that you operate; place the server behind a trusted reverse proxy or tunnel and set CHATBOTTOOL_PUBLIC_BASE_URL to that origin.

Tool families

Security defaults

• Common secret paths such as .env, SSH keys, PEM files, and private keys are blocked.

• Symlink escapes and case-only path confusion are rejected.

• Network fetch is full-mode only and requires an explicit hostname allowlist.

• HTTP MCP uses OAuth and host-header validation.

• Audit events redact common secret-bearing input fields.

• Shell, writes, tools, widgets, network hosts, and secret names have independent policies.

Read the complete security model and deployment checklist.

Verify

npm test
npm run typecheck
npm audit --omit=dev
node dist/cli.js doctor

The suite verifies both published surfaces: exactly 37 standard tools and 53 full-mode tools, alongside workspace confinement, OAuth, secret blocking, checkpoint recovery, audit redaction, and controlled Git behavior.

Project status

Chatbottool MCP is an early public extraction. Its security boundaries and tool surfaces are tested, but configuration and public APIs may evolve before 1.0.

License

MIT. See LICENSE and NOTICE.md.