baan
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
baan lets AI apps like Gemini, Claude or ChatGPT use tools on your own computer over the internet, with a login page built in. One codebase for Linux, macOS and Windows.
4 built-in tools, same as pi:
read,write,edit,bash(powershellon Windows). Each can be turned off.Everything else is a plugin. The repo ships one:
image, which letsreadsend pictures at original resolution, never resized or recompressed. It adds no new tool, so the AI app's tool list (and its approvals) doesn't change.Built-in login. Standard MCP OAuth (dynamic client registration + PKCE) with a password page served by baan itself. No Google Cloud project, no GitHub app.
Survives restarts. Stateless MCP + tokens saved to disk, so restarting baan doesn't disconnect your AI app.
No hardcoded values. Everything is in
baan.ymlor env vars.
⚠️ Read this first. Anyone who logs in can do whatever the enabled tools allow.
bash/powershell= full control of your computer as your user, and it is not limited byworkspace.allow. Plugins run with your full rights too. Keep the password to yourself (setup makes a long random one), keep baan on127.0.0.1behind a tunnel, and turn off what you don't need.
Quick start
You need Node.js 22.18+ and Git. Same commands on Linux, macOS and Windows:
git clone https://github.com/mychicken0/baan-mcp.git
cd baan-mcp
npm install
npm startThat's it. npm start walks you through everything, with colors and icons, and you mostly just press Enter:
Folder the AI may work in (default: your home folder).
What it may do: ⭐ everything like pi: read, write, edit and run commands (recommended) / files only / read only.
Internet address. No domain needed: baan sets up Tailscale Funnel for you. It installs Tailscale if missing (Linux), opens the free sign-in page in your browser, turns Funnel on, and finds your
https://<computer>.<tailnet>.ts.netaddress itself. Already have Cloudflare Tunnel or your own domain? Pick that instead.Keep it running: ⭐ always, in the background, and start with the computer (recommended) / only while the window is open.
Password is made for you.
At the end it prints the URL to paste into your AI app (also copied to the clipboard) and the password for the login page. In background mode you can then close the window: baan keeps running and comes back by itself after a reboot. No admin rights needed:
OS | How it starts with the computer |
Linux | systemd user service ( |
macOS | launchd agent ( |
Windows | hidden launcher in the Startup folder, at login. No console window |
Picked "only while the window is open"? Press b in the baan window any time to move it to the background.
Changing things later: edit the config (npm run config, or press c in the baan window) and save. baan checks it and restarts by itself. It does the same when a plugin's code changes. If the new config is broken, the old server keeps running and you see the error. This works in the background too. Keys in the baan window: b run in background, p control panel, r restart, c edit config, g guide, q quit.
🏠 Control panel (an app with buttons)
Setup puts a baan icon with the house logo in the baan folder, made for your OS: baan.desktop (Linux), baan.app (macOS) or baan.lnk (Windows). Double-click it, even when every window is closed, and the control panel opens in its own window:
status, the URL for your AI app (📋 copy), whether it starts with the computer
Start / Stop / Restart, and Run in background for a baan running in a terminal
settings: folder, what the AI may do, plugins, port. Save checks everything first, then baan restarts by itself
make a new password, read the log, open the config file or this guide
It also opens with npm run panel or key p in the baan window. No icon (set up before it existed, or moved the folder)? npm run app makes it. You can drag the icon to your desktop, dock or taskbar.
The panel is for this computer only: it listens on 127.0.0.1 on its own port (baan's port + 1), never on the MCP port that Tailscale Funnel / your tunnel exposes, and every request needs a random key that only the icon knows. It closes by itself when its window is closed; closing it never stops baan.
📖 GUIDE.md: change settings, add or remove plugins, write your own plugin, troubleshooting.
Related MCP server: AKIMCP
Commands
| first run: guided setup. Then run, and restart by itself on changes |
| run the guided setup again |
| run in the background and start with the computer |
| stop the background copy; it no longer starts with the computer |
| running? URL, config and log location |
| last lines of the background log |
| open the control panel window |
| make the baan icon in the baan folder (opens the control panel) |
| open the config file in an editor |
| check the config and load every plugin, without starting |
| new random password; signs out every connected app |
| create config + password without questions (scripts) |
| run once, no auto-restart (for services and scripts) |
| list enabled tools |
Every command takes --config FILE. Env overrides: BAAN_CONFIG, BAAN_DATA_DIR, BAAN_HOST, BAAN_PORT, BAAN_PUBLIC_URL.
Getting a public https URL
baan only listens on 127.0.0.1; the AI app reaches it through a tunnel. The URL must not change (a changing URL disconnects your AI app).
Tailscale Funnel (default in setup, no domain): setup runs
tailscale funnel --bg --https=443 http://127.0.0.1:<port>. If port 443 is already used by another Tailscale service, it uses 8443 or 10000 instead and never overwrites it. The first time, Tailscale asks you to allow Funnel in the browser.Your own domain (Cloudflare Tunnel, reverse proxy): point it at
http://127.0.0.1:<port>and enter the address in setup.
Plugins
Full how-to in GUIDE.md.
plugins:
image: { from: baan-plugin-image, maxBytes: 20971520 } # bundled package in plugins/image
mytool: { from: ./my-plugin.ts } # local file
other: { from: some-npm-package } # installed package (must ship JS)
image: false # keep installed, turn offA plugin's default export is a factory. It receives z (zod), so it needs no dependencies:
import type { PluginFactory } from "baan-mcp/src/plugin.ts";
const plugin: PluginFactory = ({ z, options }) => ({
name: "hello",
tools: [{
name: "hello",
description: "Say hello",
input: { name: z.string() },
readOnly: true,
run: async ({ name }, ctx) => `hello ${name}`, // or [{type:"text"...},{type:"image"...}]
}],
});
export default plugin;ctx.resolvePath(p) expands ~, resolves relative paths and enforces workspace.allow.
image plugin
With it on, read on a picture checks the file's real format (PNG, JPEG, GIF, WebP), reads its width × height from the header, and sends the bytes unchanged. Files over maxBytes are refused instead of shrunk. (The AI app may still scale images on its own side; baan never does.)
Exception: apps that drop image blocks from tool results. The Gemini web app (it registers as Google) passes only text to the model, so for apps listed in textClients (default [Google]) read sends the picture as base64 JPEG text instead, scaled to fit textMaxDim px (default 768, quality textQuality 80) with ImageMagick. The model decodes it on its side (e.g. in its code tool) and looks at it. Set textClients: [] to turn this off.
Security notes
Password is stored as a scrypt hash; access/refresh tokens are stored as SHA-256 hashes in
state.json(mode 600).Login page locks after
auth.maxFailedLoginswrong passwords forauth.lockoutSec.Every tool call is appended to
audit.log(long arguments clipped).
Development
npm run typecheck
npm test # end-to-end: OAuth flow + all tools + image bytes unchangedStatus
Early prototype. Planned: a setup page in the browser, baan plugin add/remove, single-file installers.
Inspired by pi (minimal tool set) and DeepSeek Harness (everything is a plugin). Not affiliated with either.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Reach your own computers from any AI app: files, search, commands, approvals and outage alerts.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search, update, manage files, and run terminal commands on a computer, with remote access via Streamable HTTP and OAuth 2.0 for integration with ChatGPT and web agents.1,287,096 npm1MIT
- FlicenseNot gradedqualityAmaintenanceExposes an OAuth-gated suite of 38 tools that let web-based AI chat clients securely operate a local machine, covering files, shell, search, Git, SQLite, browser automation, DevTools, background tasks, localhost services, clipboard, notifications, ports, and Postman. A strict command whitelist and configurable folder allowlist keep that broad local access governed rather than unrestricted.-
- FlicenseNot gradedqualityBmaintenanceTurns web-based AI chat clients into secure operators of a local machine by exposing a governed, OAuth-gated set of 38 tools for file read/write/edit, whitelisted shell commands, search, Git, SQLite, browser automation, DevTools, background tasks, localhost/LAN fetching, clipboard, notifications, ports, Postman, and AIObox windows. Access is confined to user-approved folders with a strict command whitelist, rate limits, and a security log.-
- AlicenseNot gradedqualityAmaintenanceExposes a governed suite of 38 OAuth-gated tools that let web-based AI chat clients read, write, edit, and search local files, run whitelisted shell commands, inspect databases and localhost APIs, drive browsers and DevTools, and manage background tasks, Git, clipboard, notifications, and ports. Local IDEs connect directly over loopback, while remote clients reach the same machine through a secure tunnel.MIT