aki-mcp-sv
Mã nguồn mở v2.2.0Một lệnh npx @akinet/akimcp biến máy tính thành MCP server để Claude web và ChatGPT đọc/sửa file, chạy shell, điều khiển Chrome và chạy tác vụ nền, không cần cài app desktop.
github.com/lacvietanh/aki-mcp-sv · Windows · Linux · macOS · MCP · Tailscale Funnel
aki-mcp-sv (gói npm @akinet/akimcp) là MCP server mã nguồn mở (giấy phép MIT) mở filesystem, shell, Chrome và tác vụ nền của máy cá nhân ra cho Claude.ai, ChatGPT, Grok, Gemini và Postman (Gemini kết nối được nhưng điều khiển tool vẫn đang hoàn thiện) qua Tailscale Funnel (hoặc một Cloudflare tunnel tuỳ chọn), 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 — cài bằng một lệnh npm i -g @akinet/akimcp hoặc chạy thử ngay bằng npx. 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: Cài toàn cục qua npm (khuyến nghị)
npm install -g @akinet/akimcp && akimcpGói npm @akinet/akimcp cài lệnh akimcp toàn cục. Không muốn cài, chạy thử ngay bằng npx @akinet/akimcp. Không có gì cài ngoài user directory, không tạo daemon nền, không cần sudo/quyền quản trị.
Cách 2: Cài từ source (cho contributor)
git clone https://github.com/lacvietanh/aki-mcp-sv.git && cd aki-mcp-sv && npm install && npm run devYêu cầu: Node.js, tài khoản Tailscale đã bật Funnel (miễn phí trên mọi gói).
- Chạy được trên Windows, Linux, macOS — cài bằng npm i -g @akinet/akimcp (lệnh akimcp) hoặc npx @akinet/akimcp, không cần clone repo
- Local-first: Gatekeeper luôn bind 127.0.0.1:9999 với Bearer auth; Cursor, Claude Code, AGY, Codex và Postman kết nối trực tiếp, còn Tailscale Funnel/Cloudflare Tunnel chỉ là ingress tuỳ chọn cho client Web
- Kết nối được Claude.ai, Gemini (dán tay client ID/secret), ChatGPT, Grok (tự đăng ký qua DCR RFC 7591) và Postman (bearer token đã mint) — Claude/ChatGPT/Grok đáng tin cậy, Gemini kết nối được nhưng chưa điều khiển tool ổn định
- Từ 2.0.0: mọi tool đổi tiền tố local__* → aki__*, toàn bộ arm/connector cũ phải kết nối lại
- Background Task Runner (aki__task_start/aki__task_manage): chạy lệnh nền không đồng bộ, log stream thẳng ra đĩa, dọn cả process group khi kill
- Điều khiển Chrome thật qua CDP (aki__chrome_launch/tabs/interact): clone hồ sơ Chrome/Brave/Edge, gõ chữ như người dùng, chụp ảnh màn hình, dò quota AI đang đăng nhập
- aki__local_fetch: gọi HTTP tới localhost/mạng LAN có chặn SSRF 5 lớp (chặn cloud metadata, IPv6 link-local, giới hạn 512KB/15s)
- Shell whitelist deny-by-default + trusted script dirs; find/sort không còn mặc định
- aki__find_path ~0,2s/164k file; aki__search_content mặc định regex -iE
- Từ 2.1.0: Gatekeeper luôn bind 127.0.0.1; ingress là tuỳ chọn; panel chia nhóm Local/Web, thêm connector Codex và giữ các tab IDE local
- Từ 2.2.0: panel mục 7 hiển thị ai đang giữ quyền truy cập và ai đang dùng; gatekeeper chặn 15 phút (429) sau 5 lần sai credential trong 60 giây; passphrase và access token được che, roll được ngay trên panel
- Lỗi xác thực trả 401 khi token sai; kết nối Web trả 503 khi ingress chưa sẵn sàng; Postman khôi phục hard-lock cho subagent shell
- Tự kiểm tra bản mới của cả aki-mcp-sv lẫn AkiDevRule mỗi lần khởi động
- MIT — GitHub là nguồn chân lý
- Từ 07/08 đến 01/10/2026: 1.0.0 → 2.2.0. 2.2.0 (01/10) thêm mục bảo mật & giới hạn kết nối trên panel, rate limit lần kết nối sai, che và roll passphrase/token, gộp ba tool git thành aki__git chỉ đọc, một access token dùng chung thay vì mỗi grant một token. 2.1.0 (18/09) chuyển sang local-first: Gatekeeper luôn bind 127.0.0.1, ingress tuỳ chọn, thêm Codex và nhóm panel Local/Web, mã lỗi 401/503 rõ ràng, giữ tab IDE local, khôi phục hard-lock Postman subagent shell và bỏ fallback install.py Windows đã chết. Trước đó: 2.0.0 (13/09) rebrand npm @akinet/akimcp + tool prefix aki__*, Task Runner, Chrome automation, local_fetch, git/SQLite/port tools; 2.0.1 (13/09) fix panel "wrong token" ở lần chạy thứ hai; 2.0.2 (13/09) viết lại setup/onboarding theo flow v2; 2.0.3 (15/09) vá lỗ hổng bảo mật deps; 2.0.4 (15/09) sửa panel Postman không tự gắn lại sau khi app quit/reopen. Trước đó 1.15.0 (07/09) context-length bar + credit reset countdown + summarize-for-handoff
Đ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 local-first, ingress tách rời
Từ 2.1.0, gatekeeper.js luôn bind 127.0.0.1:9999 và phục vụ client local kể cả khi không có internet. Tailscale Funnel/Cloudflare Tunnel là reverse proxy tuỳ chọn cho client Web/mobile; panel quản trị vẫn chỉ bind 127.0.0.1:9998.
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), hoặc trang giới thiệu công khai tại akimcp.top.
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 npx @akinet/akimcp. Client local kết nối trực tiếp; client Web dùng ingress khi cần.
Xem trên GitHub