LOCAL MCP CONNECTION

Your agent.
Your tools.

Piwi works with clients that support MCP over stdio. You need Node.js 22 or later, Git, and a running Docker engine.

1. Install and build

Clone the repository and build the sandbox images. The build writes immutable image IDs to .piwi/images.json; the local MCP server reads that map at startup.

Terminal

git clone https://github.com/AdrianBesleaga/piwi-capsules.git
cd piwi-capsules
npm ci
npm run capsules:build

2. Add Piwi to your MCP client

Replace both absolute paths with your checkout location. Use your client's local stdio server configuration; the precise settings format can vary. Restart the connection after building new images.

Common MCP client configuration

{
  "mcpServers": {
    "piwi": {
      "command": "node",
      "args": [
        "/absolute/path/piwi-capsules/node_modules/tsx/dist/cli.mjs",
        "/absolute/path/piwi-capsules/mcp/stdio.ts"
      ]
    }
  }
}

3. Verify the connection

Ask your agent to list Piwi tools, then call piwi_run_text_stats with the request below. The expected result is 10 characters, 2 words, 1 line, and 10 UTF-8 bytes.

Tool arguments

{ "input": { "text": "Hello Piwi" } }

If tools do not appear

Check that Docker is running and the image build completed.
Check that both configuration paths are absolute and exist.
An explicit PIWI_CAPSULE_IMAGES environment variable overrides the saved image map. Remove an outdated override or update it.
Restart the MCP server after changing the configuration.

Where your data goes

The MCP client sends each request to your local server. The server starts a container with no network access and a read-only root filesystem, reads the JSON result, and removes temporary job files. Your client may retain conversation history according to its own settings.

There is no hosted execution endpoint or account to create. Read the source and choose a host you trust before processing sensitive information.