Get started

Install and run Aki MCP Server

No installer to download: one npm command, or clone and run from source. It takes a few minutes.

A word you do not know? Words you will meet

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 web AI apps: Tailscale installed and signed in with a free account, with Funnel turned on once for it. AI apps on this computer skip this: they connect directly (127.0.0.1 or stdio).
  • An AI app that supports custom MCP connectors, in the browser or on your computer, or a web chat that can send HTTP requests. The connect page has steps for each one.

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 happens when it starts

  • Enables Tailscale Funnel on port 9999 automatically when needed.
  • Creates your passphrase, the secret phrase you type once when a web AI app connects, and starts the gatekeeper that checks every call.
  • Opens the control panel in your browser at 127.0.0.1:9998. You choose allowed folders and commands there, and copy the settings for each AI app: that is your next step.

Only for web AI apps: a public address

Web AI apps run on the internet, so they need a public HTTPS address (an ingress) that leads to your computer. Pick one; AI apps on this computer need none.

Tailscale Funnel (default)

Free on every Tailscale plan: turn it on once with the link AkiMCP prints, then the server uses port 9999.

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 installed outside your user folder, no background service, and no sudo or administrator rights 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.