aki-mcp-sv
Open Source v2.2.0One npx @akinet/akimcp command turns a machine into an MCP server so Claude web and ChatGPT can read/edit files, run shell, drive Chrome, and run background tasks — no desktop app install needed.
github.com/lacvietanh/aki-mcp-sv · Windows · Linux · macOS · MCP · Tailscale Funnel
aki-mcp-sv (npm package @akinet/akimcp) is an open-source (MIT License) MCP server that exposes a personal machine's filesystem, shell, Chrome and background tasks to Claude.ai, ChatGPT, Grok, Gemini and Postman (Gemini connects, though tool-driving is still being ironed out) over Tailscale Funnel (or an optional Cloudflare tunnel), authenticated with OAuth 2.1. No desktop app install, no device-locked quota — install is a single npm i -g @akinet/akimcp command, or try it instantly via npx. Shell access runs through a read-only-by-default whitelist, unlike Desktop Commander's blocklist model. The GitHub repository is the single source of truth.
Option 1: Global npm install (recommended)
npm install -g @akinet/akimcp && akimcpThe @akinet/akimcp npm package installs the akimcp command globally. To try it without installing, run npx @akinet/akimcp instead. Nothing is installed outside the user directory, no background daemon is created, no sudo/admin privileges required.
Option 2: Install from source (for contributors)
git clone https://github.com/lacvietanh/aki-mcp-sv.git && cd aki-mcp-sv && npm install && npm run devRequirements: Node.js, a Tailscale account with Funnel enabled (free on every plan).
- Runs on Windows, Linux, macOS — install via npm i -g @akinet/akimcp (the akimcp command) or npx @akinet/akimcp, no repo clone needed
- Local-first: Gatekeeper always binds 127.0.0.1:9999 with Bearer auth; Cursor, Claude Code, AGY, Codex, and Postman connect directly, while Tailscale Funnel/Cloudflare Tunnel is optional ingress for Web clients
- Connects Claude.ai, Gemini (pasted client ID/secret), ChatGPT, Grok (self-register via RFC 7591 DCR) and Postman (minted bearer token) — Claude/ChatGPT/Grok are reliable, Gemini connects but doesn't yet drive tools reliably
- Since 2.0.0: every tool renamed from local__* to aki__*, all existing arms/connectors must reconnect
- Background Task Runner (aki__task_start/aki__task_manage): detached async command execution, zero-RAM disk log streaming, process-group teardown on kill
- Real Chrome control over CDP (aki__chrome_launch/tabs/interact): clones Chrome/Brave/Edge profiles, synthetic human-like typing, screenshots, live AI quota probing
- aki__local_fetch: HTTP calls to localhost/LAN with 5-layer SSRF protection (blocks cloud metadata, IPv6 link-local, 512KB/15s caps)
- Deny-by-default shell whitelist + trusted script dirs; find/sort not default
- aki__find_path ~0.2s/164k files; aki__search_content defaults to -iE regex
- Since 2.1.0: Gatekeeper always binds 127.0.0.1; ingress is optional; the panel groups Local/Web clients, adds a Codex connector, and retains local IDE tabs
- Since 2.2.0: panel section 7 shows who holds access and who uses it; the gatekeeper blocks a caller for 15 minutes (429) after 5 rejected credentials in 60 seconds; the passphrase and access token are masked and can be rolled from the panel
- Authentication returns 401 for a bad token; Web connections return 503 when ingress is unavailable; Postman restores the subagent-shell hard lock
- Checks for new releases of both aki-mcp-sv and AkiDevRule on every startup
- MIT — GitHub is source of truth
- Releases 2026-08-07 to 2026-10-01: 1.0.0 → 2.2.0. 2.2.0 (10-01) adds a security & connection-limits panel section, rate limiting of failed connection attempts, masked and rollable passphrase/token, merges the three git tools into one read-only aki__git, and uses one shared access token instead of one per grant. 2.1.0 (09-18) made ingress optional with Gatekeeper fixed to 127.0.0.1, added Codex and Local/Web panel groups, explicit 401/503 handling, retained local IDE tabs, restored the Postman subagent-shell hard lock, and removed the dead Windows install.py fallback. Earlier: 2.0.0 (09-13) rebranded to npm @akinet/akimcp + aki__* tool prefix, added the Task Runner, Chrome automation, local_fetch, git/SQLite/port tools; 2.0.1 (09-13) fixed the "wrong token" panel bug on a second launch; 2.0.2 (09-13) rewrote setup/onboarding for the v2 flow; 2.0.3 (09-15) patched dependency security advisories; 2.0.4 (09-15) fixed the Postman panel not re-attaching after Postman quit/reopened. Earlier: 1.15.0 (09-07) context-length bar + credit reset countdown + summarize-for-handoff
Core Ideas
Whitelist, not blocklist
Desktop Commander, the most popular MCP terminal server for Claude Desktop, blocks shell commands with a blocklist (deny-listed commands, allow by default) and runs locally over stdio, not designed to be exposed to the internet. aki-mcp-sv does the opposite: nothing runs unless explicitly declared in the allowlist, down to the subcommand (git is scoped to status/log/diff/show only).
Local-first Gatekeeper, decoupled ingress
Since 2.1.0, gatekeeper.js always binds 127.0.0.1:9999 and serves local clients even without internet access. Tailscale Funnel/Cloudflare Tunnel is an optional reverse proxy for Web/mobile clients; the admin panel still binds only 127.0.0.1:9998.
OAuth 2.1: Claude/Gemini paste in, ChatGPT/Grok self-register
claude.ai defaults to attempting Dynamic Client Registration (DCR) first; aki-mcp-sv doesn't advertise that endpoint to Claude, so client_id/client_secret are generated once at npm start and pasted manually into Advanced settings; Gemini reuses that same client. ChatGPT and Grok do the opposite, self-registering via POST /register (RFC 7591) as public clients, each with its own redirect URI. All four still have to clear the passphrase screen and PKCE before getting a token.
Kiro CLI: read-only arm (kiro_write removed)
kiro_read (--trust-tools=fs_read) locks the model to sonnet-4.5; verified against kiro-cli 2.16.2. kiro_write was removed in 1.3.0 as it duplicated the session filesystem write path — file writes go through the connector's filesystem MCP arm.
find_path instead of the default search_files
The default search_files tool doesn't return directories and times out easily on large trees. find_path scans the whole tree in one call, measured at ~0.2s over 164,000 files / 11,700 directories, returns both files and directories, and skips node_modules/.git automatically.
Two layers block unauthorized access
A 10-character passphrase at /authorize (~50 bits of entropy, no bare Approve button since /authorize is a public endpoint), plus PKCE S256 so access tokens only go to the client holding the matching code_verifier.
execFile, never a real shell
shell-mcp.js runs commands via execFile, never through a real shell, so command-chaining characters (; & | `) are blocked at the execution layer rather than by string filtering.
1.7.0: a swappable public edge
From 1.7.0, beside the default Tailscale Funnel you can run through your own Cloudflare tunnel with --tunnel (JSON credentials, --origin supplies the hostname, forward fixed at 9999), or point straight at a self-run HTTPS origin via PUBLIC_ORIGIN. Precedence: --tunnel > PUBLIC_ORIGIN > Funnel. It is an option for regions where Funnel intermittently drops requests, not a claim that Cloudflare is more reliable.
Compared to other remote MCP patterns
| Project | Internet exposure | Auth | Shell model |
|---|---|---|---|
| aki-mcp-sv | Tailscale Funnel, self-hosted | OAuth 2.1 (Claude/Gemini pasted, ChatGPT/Grok DCR) | Whitelist, read-only by default |
| Desktop Commander | None — local stdio | None | Blocklist, allow by default |
| mcp-remote (geelen) | Doesn't expose anything — a client-side bridge | OAuth 2.1 + PKCE + DCR (client side) | None, just a pipe |
| server-filesystem (Anthropic) | None — local stdio/Docker | None | No shell tool at all |
mcp-remote isn't a competing server: it's a client-side bridge that lets stdio-only apps talk to a remote MCP server that already exists elsewhere, and doesn't provide any filesystem or shell access on its own.
Author
Lạc Việt Anh — founder of the Aki ecosystem. aki-mcp-sv distills how he uses Claude web to work on real code, released as open source under the MIT License. Version 1.1.0 (Windows support + the ChatGPT connector) includes a contribution from capybara (okdev888) via PR #1; the 1.2.x line added Gemini, Grok, and the Kiro CLI arm.
aki-mcp-sv belongs to the ecosystem's dev-tooling layer, alongside AkiDevRule and Aki Dev Sync. See more technical write-ups at AkiDEV (dev.akitao.com), or the public landing page at akimcp.top.
Frequently Asked Questions
What is aki-mcp-sv?
How do I install it?
Why whitelist instead of blocklist for shell?
Is it safe to expose a machine to the internet?
One npx @akinet/akimcp command. Local clients connect directly; Web clients use ingress when needed.
View on GitHub