Local server and MCP

1. Start and connect

MCP connects the chat to computer tools and external services. You need the local ZeroChat server. Choose one installation method:

PyPI (recommended)

Linux, macOS and Android (Termux):

pip install zerochat
zerochat

Windows (PowerShell or CMD): use the py launcher, which works even if Python's Scripts folder is not on PATH.

py -m pip install zerochat
py -m zerochat

Direct download

Linux, macOS and Android (Termux):

curl -fsSL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py
python3 zerochat.py

Windows (PowerShell or CMD): curl.exe ships with Windows 10 and 11; in PowerShell type it with .exe to avoid the Invoke-WebRequest alias.

curl.exe -fsSL https://albalday.github.io/zerochat/zerochat.py -o zerochat.py
py zerochat.py

For subsequent launches, use zerochat (or py -m zerochat on Windows) or python3 zerochat.py (py zerochat.py on Windows), respectively. Both open GitHub Pages and store local data in ~/zerochat/.

1. Keep the server running and open the link it provides.
2. Go to Settings → MCP and check the connection and discovered tools.
3. Enable the tools you need and review their permissions.

The link zerochat opens the browser with carries the daily token; the page stores it and reconnects by itself on later launches. If disconnected, check that the process is running and review the browser's local network access permissions. For a server on another port, on another computer (through an SSH tunnel) or behind a reverse proxy, use the Connection panel (the plug icon next to the settings wheel in the sidebar): turn off Local connection, enter its URL and press Connect. If the token is missing or has expired (it changes every day), the page asks for the user name and password of the account running zerochat; the password is not stored. Do not share the startup link.

Usage modes, local data and updates →

2. Use computer tools

• Files: list_directory, read_file, write_file, edit_file and search_files.
• Commands: run_command runs each command in a fresh shell that starts in the project directory: a cd, an export or an activated virtual environment does not carry over to the next call, so the model chains them with && in the same command. The output combines stdout and stderr in the order they are produced. By default it waits up to 30 seconds (the model can ask for up to 10 minutes) and, if the command has not finished, stops it together with any processes it started. For servers, file watchers or long tasks, the model starts it in the background and follows or stops it with check_command. If a background command finishes without the model checking it, your next message tells the model how it ended, with its last lines; that note is not shown in the chat. Each command appears in the chat as a card showing its status and duration (running, in background, finished, exit code, timed out or stopped). Expanding it shows the command's log, which keeps updating while it runs, and Stop terminates it. If background commands are still running when a reply finishes, a collapsed notice is added at the end of the chat; expanding it lists them with their elapsed time, and each one leads to its card. The notice does not update: each command's status is in its card. If closing the tab will stop ZeroChat, the browser asks for confirmation while commands are running. Pressing Stop in the chat also stops the commands the turn was waiting for, and closing ZeroChat stops all of them. If ZeroChat dies abruptly, Windows stops them immediately; on Linux, macOS and Android they are stopped the next time it starts. On Linux/macOS/Android it uses bash/sh; on Windows, PowerShell.
• Syntax checks: get_diagnostics; it does not replace project tests.
• Browser: browser_action requires Node.js and having Chrome or Edge on your system (or Chromium). To use it, start the Playwright service in Settings → MCP (it installs automatically) and choose it in Settings › Browser. See the browser help.

Tool results become part of the conversation and may be sent to the selected model.

3. Start an external MCP service

In Settings → MCP → Available MCP servers, configure each service and select Start. ZeroChat prepares its declared dependencies. To stop a service, select Stop.

winget install OpenJS.NodeJS.LTS

Startup and OAuth

The button shows Starting and stays disabled. If startup exceeds 15 seconds, ZeroChat checks the status and waits in 15-second intervals: up to 20 minutes while it installs dependencies (for example, Playwright and its browser) or awaits OAuth authorization, and up to ten more intervals while it starts. Installation and the OAuth wait are not treated as failures when the first timeout expires; once the service is active, the panel updates automatically. The button shows the attempt number.

If the service needs OAuth, its card shows an Authorization required notice with an Authorize in browser button. ZeroChat tries to open the authorization tab; if the browser blocks it, press the button. Because it opens from the web page itself, it also works on Android and Termux. If the wait expires, the service may still be starting; reload the page to check the outcome.

Services are not restarted automatically on the next ZeroChat startup. If any were active in the previous session, a dialog lists them when connecting: remove the ones you do not want with the X and press Start to launch the rest, or Do not start to leave them stopped. Services that are not started are saved as not started and are not offered again. If any fails, ZeroChat reports it and the error stays on its card in this panel.

Actions in this panel apply immediately: they do not need Save.

If installation fails

Read the card's error. Check node --version, npm --version, network access and free disk space, then try again. You do not need to reinstall ZeroChat. On Windows, see Install Node.js on Windows.

4. Review permissions

In Settings → Permissions, choose the global policy and review saved authorizations. In the MCP panel, choose Ask, Allow or Deny for each tool.

• Ask for authorization: prompts when existing rules do not resolve the call.
• Trust the workspace: besides directory rules, allows files with relative paths inside the project and simple commands: no chaining (;, &&, $()), no redirection to files, no absolute paths, ~, variables or .., and pipes only into filters such as head, grep or wc. Anything else asks for confirmation. It is not isolation: a simple command such as python3 script.py acts with your permissions.
• Allow everything: runs without confirmation, except for explicit blocks that take precedence.

Decisions may apply to one call, the backend session or permanently. External tools are named <service>_<tool>: trusting composio authorizes its tools, not those of other services. Allowing one tool does not authorize the whole service.

Allowed directories: one rule per line, with R: (read), W: (write) or RW: (both). Use * for one segment and ** for subdirectories. An empty list adds a read rule for the startup directory. Paths with ~ or variables are not resolved in the browser and always ask for confirmation: use absolute paths. Commands also have prefix rules and additional checks.

Always allow a command: authorizes only that program, without chaining, pipes or redirection to files. A leading cd <folder> && is accepted when a directory rule covers the folder, as is the command working directory. Authorizing a program trusts all of its options: git can run other commands through its configuration or aliases.

These rules are not an operating system sandbox. Authorized commands and services act with the local process's permissions. Stopping a call does not undo its changes.

5. Add your own service

Create a new folder under ~/zerochat/services/ with its own name and unique id. Use ejemplo as the template: service.json is required; add installer.json only for npm packages. The template's README.md documents the fields, including an optional help link.

You can ask the agent to create the definition using either prompt below. Replace the placeholders. The agent prepares files; you enter credentials and start the service.

I want to create the local MCP <mcp-name> for ZeroChat.
Locate the user's home directory and read README.md, service.json
and installer.json.example in zerochat/services/ejemplo using
absolute paths. Follow the README instructions.
Read the MCP's official documentation and create a sibling folder
with its own name and id; do not modify the bundled services.
If it needs an API key, put PASTE_API_KEY_HERE in service.json,
inside the env object under launch, using the required variable.
I will manually replace the placeholder with my key in service.json.
Do not ask for my key or create a launch.env or .env file.
Give me the absolute JSON path and the field to edit manually.
Do not install or start it; I will do that from Settings → MCP.

I want to create the remote MCP <mcp-name> for ZeroChat.
Its endpoint is <mcp-url>.
Locate the user's home directory and read README.md in
zerochat/services/ejemplo and the JSON files in
zerochat/services/composio using absolute paths. Follow the README
and use Composio as an example of a managed stdio mcp-remote bridge.
Create a sibling folder with its own name and id and bilingual text.
Read the MCP's and bridge's official documentation to adapt the
endpoint, transport and authentication. Verify Composio's specific
OAuth and protocol options before copying any of them.
Keep HOME and USERPROFILE isolated inside ${serviceDir}.
If an API key is required, put PASTE_API_KEY_HERE in service.json,
inside the env object under launch. I will enter my key manually
in service.json; do not create a launch.env or .env file.
Configure --header with the provider's required header and a
reference to that variable; mcp-remote will resolve the reference.
Do not ask for my key or put it in the arguments or URL.
Give me the absolute JSON path and the field to edit manually.
Do not install or start it; I will do that from Settings → MCP.

If the new folder does not appear in Settings → MCP, restart ZeroChat and reconnect. Your own folders survive updates. Bundled definitions (ejemplo, composio, playwright, memory) are restored at startup; create a copy with a new name and id instead of editing them. Do not copy dependencies or OAuth credentials.

6. Enter an API key

launch.env means the env object under launch in service.json; it is not a file. The agent leaves the placeholder and you manually enter the real key in that JSON.

1. Stop the service if it is running. Open your folder's service.json.
2. Replace PASTE_API_KEY_HERE inside launch.env with the real key, using the exact variable name required by the provider. Do not paste it into the chat.
3. Save valid JSON. On Linux or Termux restrict access with chmod 600 /absolute/path/zerochat/services/my-service/service.json.
4. Start the service from Settings → MCP.

The key is stored in plain text: do not share or commit this file. Deleting ~/zerochat/ also removes services and credentials; keep a private backup if needed.

"env": {
  "SERVICE_API_KEY": "PASTE_API_KEY_HERE"
}

"args": [
  "${serviceDir}/node_modules/mcp-remote/dist/proxy.js",
  "https://mcp.example.com/mcp",
  "--header",
  "Authorization: Bearer ${REMOTE_API_KEY}"
],
"env": {
  "HOME": "${serviceDir}",
  "USERPROFILE": "${serviceDir}",
  "REMOTE_API_KEY": "PASTE_API_KEY_HERE"
}