aki-mcp-sv
Mã nguồn mở v1.9.3Một lệnh npm start biến máy tính thành MCP server để Claude web và ChatGPT đọc, sửa file và chạy shell, không cần cài app desktop.
github.com/lacvietanh/aki-mcp-sv · Windows · Linux · macOS · MCP · Tailscale Funnel
aki-mcp-sv là MCP server mã nguồn mở (giấy phép MIT) mở filesystem và shell của máy cá nhân ra cho Claude.ai, ChatGPT và Grok (Gemini cũng xác thực được, đang hoàn thiện phần điều khiển tool) qua Tailscale Funnel (hoặc một Cloudflare tunnel tuỳ chọn từ bản 1.7.0), xác thực bằng OAuth 2.1. Không cần cài app desktop, không cần thiết bị nào ràng buộc quota — và từ 1.8.0, nếu dùng standalone launcher thì không cần cài gì cả, kể cả Node.js. Shell chạy qua whitelist mặc định chỉ đọc, khác hẳn cơ chế blocklist của Desktop Commander. Repo GitHub là nguồn chân lý duy nhất.
Cách 1: Standalone launcher (khuyến nghị — không cần Node.js)
Tải launcher đúng OS từ trang Releases (không phải nút xanh “Code → Download ZIP” ở trên, đó chỉ là source không chạy được): macOS mở .command, Linux chmod +x rồi chạy .run, Windows mở .cmd (vẫn cần Git for Windows/WSL trên PATH). Lần đầu tải Node runtime + payload kèm checksum; các lần sau không cần mạng. Giữ nguyên cửa sổ terminal — đó là server đang chạy, đóng là tắt luôn.
Tải launcher từ GitHub ReleasesCách 2: Cài từ source (cần Node.js)
git clone https://github.com/lacvietanh/aki-mcp-sv.git && cd aki-mcp-sv && npm install && npm startYêu cầu: Node.js, tài khoản Tailscale đã bật Funnel (miễn phí trên mọi gói). Windows cần thêm Git for Windows (hoặc WSL) trên PATH.
- Chạy được trên Windows, Linux, macOS — standalone launcher không cần Node.js, hoặc git clone + npm install + npm start
- Mở ra internet qua Tailscale Funnel (HTTPS, miễn phí trên mọi gói Tailscale)
- Kết nối được Claude.ai, Gemini (dán tay client ID/secret) và ChatGPT, Grok (tự đăng ký qua DCR RFC 7591) — Claude/ChatGPT/Grok đáng tin cậy, Gemini kết nối được nhưng chưa điều khiển tool ổn định
- Arm Kiro CLI: kiro_read (read-only); kiro_write gỡ ở 1.3.0 — ghi qua filesystem MCP session
- Shell whitelist deny-by-default + trusted script dirs; find/sort không còn mặc định
- local__find_path ~0,2s/164k file; local__search_content mặc định regex -iE
- Từ 1.5.0 gộp 8 tiến trình tool xuống 4, mọi arm về một server local__* — connector cũ phải kết nối lại
- Panel: stepper + tabs Claude/Grok/ChatGPT/Gemini, spy-TOC, mọi giá trị bấm là copy; bind 127.0.0.1
- 1.6.0 tự kiểm tra bản mới của cả aki-mcp-sv lẫn AkiDevRule mỗi lần npm start
- 1.7.0 đổi được cổng public edge: Cloudflare tunnel (--tunnel) hoặc PUBLIC_ORIGIN tự host, ưu tiên --tunnel > PUBLIC_ORIGIN > Funnel
- MIT — GitHub là nguồn chân lý
- Từ 07/08 đến 16/08/2026: 1.0.0 → 1.9.3, gồm cả bản cài standalone launcher (không cần git/npm) cho Windows/macOS/Linux
Điểm cốt lõi
Whitelist, không phải blocklist
Desktop Commander, MCP terminal server phổ biến nhất cho Claude Desktop, chặn lệnh shell bằng blocklist (liệt kê lệnh cấm, mặc định cho phép), và chạy cục bộ qua stdio, không thiết kế để lộ ra internet. aki-mcp-sv chọn ngược lại: không lệnh nào chạy được trừ khi được khai báo rõ trong allowlist, tới tận subcommand (git chỉ được scope ở status/log/diff/show).
gatekeeper.js là cổng public duy nhất
mcp-hub tự mang theo một REST API quản trị không xác thực (/api/*). Nó chỉ nghe ở loopback; gatekeeper.js là tiến trình duy nhất nhận traffic từ Funnel, nên API không xác thực đó không bao giờ chạm internet.
OAuth 2.1: Claude/Gemini dán tay, ChatGPT/Grok tự đăng ký
claude.ai mặc định thử Dynamic Client Registration (DCR) trước; aki-mcp-sv không quảng cáo endpoint đó cho Claude nên client_id/client_secret được sinh một lần lúc npm start và dán tay vào Advanced settings; Gemini tái dùng đúng client đó. ChatGPT và Grok thì ngược lại, tự đăng ký qua POST /register (RFC 7591) làm public client, mỗi bên một redirect URI riêng. Cả bốn đều phải qua màn hình passphrase và PKCE trước khi nhận token.
Kiro CLI: arm đọc-only (kiro_write đã gỡ)
Arm kiro_read (--trust-tools=fs_read) khoá model sonnet-4.5; đã verify với kiro-cli 2.16.2. kiro_write bị gỡ ở 1.3.0 vì trùng filesystem write của session — ghi file đi qua arm filesystem MCP của connector.
find_path thay vì search_files mặc định
Tool search_files mặc định không trả về thư mục và dễ timeout trên cây lớn. find_path quét toàn bộ cây trong một lần gọi, đo được ~0,2 giây trên 164.000 file / 11.700 thư mục, trả về cả file lẫn thư mục, tự bỏ qua node_modules/.git.
Hai lớp chặn truy cập trái phép
Passphrase 10 ký tự tại /authorize (~50 bit entropy, không dùng nút Approve trần vì /authorize là endpoint public), cộng PKCE S256 để access token chỉ cấp cho đúng client giữ code_verifier khớp.
execFile, không qua shell thật
shell-mcp.js thực thi lệnh bằng execFile, không bao giờ đi qua shell thật, nên các ký tự nối lệnh (; & | `) bị chặn ở tầng thực thi chứ không phải bằng lọc chuỗi.
1.7.0: cổng public edge đổi được
Từ 1.7.0, ngoài Tailscale Funnel mặc định, bạn có thể chạy qua một Cloudflare tunnel riêng bằng cờ --tunnel (credentials JSON, --origin cấp hostname, forward cố định 9999), hoặc trỏ thẳng vào một origin HTTPS tự vận hành bằng PUBLIC_ORIGIN. Thứ tự ưu tiên: --tunnel > PUBLIC_ORIGIN > Funnel. Đây là lựa chọn cho vùng mà Funnel hay rớt lẻ từng request, chưa phải tuyên bố Cloudflare bền hơn.
So với các remote MCP server khác
| Dự án | Expose ra internet | Xác thực | Mô hình shell |
|---|---|---|---|
| aki-mcp-sv | Tailscale Funnel, tự host | OAuth 2.1 (Claude/Gemini dán tay, ChatGPT/Grok DCR) | Whitelist, mặc định chỉ đọc |
| Desktop Commander | Không — stdio cục bộ | Không có | Blocklist, mặc định cho phép |
| mcp-remote (geelen) | Không tự expose — là bridge phía client | OAuth 2.1 + PKCE + DCR (ở client) | Không có, chỉ là ống dẫn |
| server-filesystem (Anthropic) | Không — stdio/Docker cục bộ | Không có | Không có shell tool nào |
mcp-remote không phải một server cạnh tranh: nó là bridge phía client giúp app chỉ hỗ trợ stdio nói chuyện được với một remote MCP server có sẵn ở nơi khác, không tự cấp filesystem hay shell nào.
Người phát triển
Lạc Việt Anh — người sáng lập hệ sinh thái Aki. aki-mcp-sv đúc kết cách anh dùng Claude web để làm việc trên code thật, và phát hành mã nguồn mở theo giấy phép MIT. Bản 1.1.0 (hỗ trợ Windows + connector ChatGPT) có đóng góp từ cộng tác viên capybara (okdev888) qua PR #1; bản 1.2.x thêm Gemini, Grok và arm Kiro CLI.
aki-mcp-sv thuộc lớp công cụ dev của hệ sinh thái, cùng nhóm với AkiDevRule và Aki Dev Sync. Xem thêm ghi chép kỹ thuật tại AkiDEV (dev.akitao.com).
Câu hỏi thường gặp
aki-mcp-sv là gì?
Cài đặt như thế nào?
Vì sao dùng whitelist thay vì blocklist cho shell?
Có an toàn khi mở máy ra internet không?
Một lệnh npm start. Claude web và ChatGPT chạm được vào máy của bạn.
Xem trên GitHub