Get started
Install and run Aki MCP Server
No desktop app and no device lock-in: one npm command, or clone and run from source. It takes a few minutes.
Prerequisites
- Node.js 22 or newer, on Windows, Linux, or macOS.
- Windows only: Git for Windows (or WSL) on
PATH, because the shell/search tools use Unix binaries. - Only for remote web AIs: Tailscale installed and signed in, with Funnel enabled once for your tailnet (free on every plan). Local IDEs skip this — they use 127.0.0.1.
- An AI client that supports custom MCP connectors: Claude web, ChatGPT, Grok, or Postman.
Option 1: Global CLI (recommended)
Published on npm. Install once, or run on demand with no install.
# Install once, run anywhere
npm install -g @akinet/akimcp
akimcp
# Or run instantly, no install
npx @akinet/akimcp
Option 2: Clone and run from source
# Clone
git clone https://github.com/lacvietanh/aki-mcp-sv.git
cd aki-mcp-sv
# Install and run
npm install
npm start
What npm start does
- Enables Tailscale Funnel on port 9999 automatically when needed.
- Generates a passphrase and starts the gatekeeper (OAuth 2.1).
- Opens the local control panel where you set allowed folders and the shell allowlist.
Expose over HTTPS (ingress options)
Tailscale Funnel (default)
Zero-config, turns on port 9999 automatically. Free on every Tailscale plan.
Cloudflare named tunnel
Run with --tunnel <cred.json> --origin <url> to route through your own tunnel.
Bring your own origin
Set PUBLIC_ORIGIN=https://your-host to point at your own HTTPS reverse proxy.
Is this safe to run?
- Nothing is installed system-wide, no daemon is created, and no sudo/administrator rights are needed.
- Settings and tokens live at
~/.aki/mcpsv/. - Most of the default shell allowlist is read-only; a few dev/OS helpers can write, so review it on a sensitive machine.
- Closing the terminal stops the server; a background task you started keeps running until you stop it.
For the full security model, see the Security page.