Skip to main content
Glama
IMPORTANT

Phần mềm có bản quyền, không phải mã nguồn mở. Chỉ đơn vị đượcNextgency cấp quyền bằng văn bản mới được cài đặt và sử dụng. Xem LICENSE.

Hướng dẫn này viết cho người không chuyên kỹ thuật: làm lần lượt từng bước, mỗi lệnh chỉ cần sao chép và dán. Toàn bộ mất khoảng 30-45 phút.

Sau khi cài, đội của bạn dán token để kết nối Meta, TikTok Ads (gồm GMV Max của TikTok Shop), Google Ads (gồm quảng cáo YouTube) và OpenAI Ads, rồi tạo link MCP cho Claude, ChatGPT, Gemini. Có thể thêm bot Telegram để nhận cảnh báo kết nối, thông báo thay đổi do AI thực hiện và tin nhắn từ AI ngay trong nhóm chat, khai báo thư mục Google Drive / Google Sheet để AI lấy ảnh, video lên quảng cáo (xem docs/huong-dan-google-drive.md), và dán token Apify để AI lấy dữ liệu sàn TMĐT, mạng xã hội, Google (giá, đánh giá sản phẩm, quảng cáo của đối thủ…) rồi phân tích (xem docs/huong-dan-apify.md). Hướng dẫn dùng: kết nối AI · Telegram · Google Drive / Google Sheet · Apify.

TIP

Cài nhanh bằng 1 lệnh (khuyến nghị cho VPS Ubuntu 22.04/24.04, Debian 12/13 mới): chép file install-ads-mcp.sh Nextgency gửi (hoặc scripts/install-ads-mcp.sh trong repo) lên VPS rồi chạy sudo bash install-ads-mcp.sh. Chỉ cần chuẩn bị tên miền, tài khoản GitHub đã được cấp quyền và 1 token (PAT classic tích cả repo + read:packages); script hỏi lần lượt, tự cài Docker, tải phần mềm, tạo cấu hình, khởi chạy và in mã cài đặt để tạo admin. Chi tiết: docs/deploy-vps.md mục 0. Các bước dưới đây là cách cài tay.

TIP

Bạn kết nối tài khoản GitHub chứa repo này với ChatGPT, Claude hoặc Gemini → cho AI đọc repo và hướng dẫn bạn deploy chi tiết nhé. Bạn cung cấp chi tiết cho AI biết là sẽ deploy trên đâu (VPS hay mini PC chạy Ubuntu Server), dùng bằng cách trỏ IP về VPS hay là Cloudflare Tunnel, trỏ IP về VPS thì có dùng Cloudflare và bật DNS only hay không. Bạn cung cấp đầy đủ ngữ cảnh để AI hướng dẫn chi tiết, gặp phần nào khó thì chụp ảnh màn hình xong gửi vào AI để nó hướng dẫn tiếp nhé.

Mục lục


Related MCP server: Ads MCP

Bước 0. Chuẩn bị

Bạn cần có:

Thứ cần có

Ghi chú

1 VPS

Ubuntu 24.04 (khuyến nghị) hoặc Debian 12. Tối thiểu 1 vCPU, 2 GB RAM, 20 GB ổ cứng. Nhà cung cấp gửi cho bạn: địa chỉ IP, tên đăng nhập, mật khẩu.

1 tên miền

Ví dụ congty.vn. Phần mềm sẽ chạy ở một tên miền con, ví dụ mcp.congty.vn.

1 tài khoản GitHub đã được Nextgency cấp quyền

Gửi tên tài khoản GitHub cho Nextgency để được thêm quyền đọc. Nên dùng tài khoản riêng cho việc này (không dùng tài khoản cá nhân chứa dự án khác).

Máy tính

Windows 10/11 hoặc macOS, có trình duyệt.

Trong hướng dẫn, thay các giá trị mẫu bằng thông tin của bạn:

Giá trị mẫu

Thay bằng

mcp.congty.vn

Tên miền con bạn dùng cho phần mềm

it@congty.vn

Email của bạn

TEN_GITHUB

Tên tài khoản GitHub đã được cấp quyền

IP_VPS

Địa chỉ IP của VPS


Bước 1. Chuẩn bị quyền GitHub

NOTE

Cài bằng script (xem đầu trang) chỉ cần1 token tích cả repo và read:packages. Cài tay theo các bước dưới đây có thể dùng 2 token như mô tả, hoặc cùng 1 token đó cho cả 2 chỗ.

Nextgency thêm tài khoản GitHub của bạn vào kho phần mềm với quyền chỉ đọc (Read). Bạn tạo 2 token (2 "mật khẩu riêng") từ tài khoản đó, mỗi token chỉ làm đúng 1 việc:

Token

Dùng để

Tích đúng 1 ô

Token A

Tải image Docker (phần mềm đã đóng gói)

read:packages

Token B

Tải mã nguồn (git clone, git pull) và để phần mềm tự kiểm tra bản mới

repo

WARNING

GitHub bắt buộc tíchrepo cho Token B (kho được chia sẻ cho tài khoản ngoài tổ chức chỉ dùng được loại token này). Quyền repo cho phép đọc và ghi mọi kho (repo) của chính tài khoản GitHub đó. Nếu tài khoản của bạn có kho quan trọng, nên tạo một tài khoản GitHub riêng cho máy chủ (ví dụ congty-ads-server) rồi gửi tên tài khoản này cho Nextgency để được thêm quyền (không bắt buộc). Với kho của Nextgency, tài khoản chỉ có quyền Read nên token không sửa được phần mềm.

1.1 Tạo Token A (tải image)

  1. Đăng nhập GitHub bằng tài khoản đã được Nextgency cấp quyền.

  2. Mở https://github.com/settings/tokens/new (Personal access tokens → Tokens (classic)).

  3. Note: gõ ads-mcp-vps-image.

  4. Expiration: chọn 1 năm (hoặc Custom ngày cụ thể). Ghi lịch nhắc gia hạn trước khi hết hạn 2 tuần.

  5. Chỉ tích ☑ read:packages. Không tích ô nào khác.

  6. Kéo xuống cuối, bấm Generate token.

  7. Sao chép token ngay (bắt đầu bằng ghp_...), lưu vào trình quản lý mật khẩu với ghi chú "Token A". GitHub chỉ hiện token một lần.

1.2 Tạo Token B (mã nguồn + kiểm tra bản mới)

Làm lại đúng như 1.1, chỉ khác:

  • Note: gõ ads-mcp-vps-repo.

  • Chỉ tích ☑ repo (các ô con bên dưới tự được tích theo). Không tích read:packages hay ô nào khác.

  • Lưu với ghi chú "Token B".

Không gửi token cho người khác, không dán vào chat/email. Token hết hạn thì phần mềm vẫn chạy bình thường, chỉ không tải hoặc kiểm tra được bản mới: tạo token mới rồi làm lại bước 4.2 (Token A) hoặc 6.2 (Token B).

IMPORTANT

Đã cài theo hướng dẫn cũ (có chạy lệnh git config --global credential.helper store, token nằm dạng chữ thường trên VPS)? Làm lần lượt trên VPS bằng user deploy:

  1. Tạo Token A và Token B mới (bước 1.1, 1.2).

  2. Xoá token cũ đang lưu trên VPS: rm -f ~/.git-credentials && git config --global --unset credential.helper. Từ giờ git pull sẽ hỏi Username (tên GitHub) và Password (dán Token B).

  3. Đăng nhập lại kho image bằng Token A: chạy docker logout ghcr.io, rồi làm bước 4.2.

  4. cd /opt/ads-mcp && nano .env, thay giá trị dòng UPDATE_GITHUB_TOKEN= bằng Token B, lưu lại, rồi chạy docker compose up -d --no-build.

  5. Vào https://github.com/settings/tokens, bấm Delete ở token cũ.

  6. Trong web, vào Cài đặt → Cập nhật, bấm Kiểm tra ngay: phải thấy phiên bản mới nhất, không báo lỗi.


Bước 2. Kết nối vào VPS

Mọi lệnh từ bước 3 trở đi được gõ trên VPS qua cửa sổ dòng lệnh.

Windows: bấm phím Windows, gõ PowerShell, mở Windows PowerShell. macOS: mở ứng dụng Terminal.

Gõ lệnh sau (thay IP_VPS bằng IP của bạn), bấm Enter:

ssh root@IP_VPS
  • Lần đầu sẽ hỏi Are you sure you want to continue connecting? → gõ yes, Enter.

  • Nhập mật khẩu VPS (khi gõ không hiện ký tự, cứ gõ rồi Enter).

  • Thấy dòng dạng root@ten-may:~# là đã vào được VPS.

Nếu bạn đăng nhập bằng user thường (nhà cung cấp cho user ubuntu, hoặc bạn ngồi trực tiếp trên mini PC, dòng nhắc dạng ten-user@ten-may:~$): gõ sudo -i, nhập mật khẩu của user đó. Dòng nhắc đổi thành root@ten-may:~# thì mới làm tiếp bước 3. Nếu không, các lệnh sẽ báo Permission denied.

Cách dán lệnh: trong PowerShell/Terminal, bấm chuột phải (Windows) hoặc Cmd+V (macOS). Nên dán từng khối lệnh trong hướng dẫn, đợi chạy xong mới dán khối tiếp theo.


Bước 3. Cài đặt máy chủ

3.1 Cập nhật hệ thống và tạo user riêng

Không nên chạy phần mềm bằng root. Tạo user tên deploy (dán cả khối):

apt update && apt -y upgrade
timedatectl set-timezone Asia/Ho_Chi_Minh
adduser --gecos "" deploy
usermod -aG sudo deploy

Lệnh adduser sẽ hỏi mật khẩu cho user deploy 2 lần, hãy đặt mật khẩu mạnh và ghi lại.

3.2 Cài Docker

Cài từ kho chính thức của Docker (dán cả khối):

. /etc/os-release
case "$ID" in ubuntu|debian) ;; *) echo "Chỉ hỗ trợ Ubuntu/Debian"; false ;; esac
apt -y install ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL "https://download.docker.com/linux/$ID/gpg" -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/$ID
Suites: ${UBUNTU_CODENAME:-$VERSION_CODENAME}
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
apt update
apt -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
usermod -aG docker deploy

Đợi 1-3 phút đến khi chạy xong.

Máy đã có Docker từ trước: kiểm tra bằng docker --version (bản 28 trở lên) và docker compose version (v2 trở lên). Đủ thì bỏ qua khối trên, chỉ chạy usermod -aG docker deploy.

Nhóm docker có quyền tương đương root trên máy chủ: chỉ thêm user quản trị tin cậy.

3.3 Tạo bộ nhớ swap (cho VPS ít RAM)

fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

3.4 Bật tường lửa

  • Nếu bạn sẽ dùng Cách A ở bước 5 (đơn giản nhất):

    apt -y install ufw git
    ufw allow OpenSSH && ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 443/udp
    ufw --force enable
  • Nếu bạn sẽ dùng Cách B - Cloudflare Tunnel:

    apt -y install ufw git
    ufw allow OpenSSH
    ufw --force enable

3.5 Chuyển sang user deploy

Thoát khỏi root:

exit

Sau đó đăng nhập bằng user deploy, chọn đúng trường hợp:

  • Kết nối từ máy tính qua SSH: gõ đủ cả @ và IP (không gõ mỗi ssh deploy):

    ssh deploy@IP_VPS
  • Ngồi trực tiếp trên mini PC / đã dùng sudo -i ở bước 2:

    su - deploy

Nhập mật khẩu của deploy đặt ở bước 3.1. Dòng nhắc phải là deploy@ten-may:~$.

Kiểm tra quyền dùng Docker:

docker ps
  • Ra một bảng (kể cả bảng trống chỉ có dòng tiêu đề CONTAINER ID ...) là đúng.

  • Nếu báo permission denied ... docker.sock: chạy sudo usermod -aG docker deploy, rồi exit và đăng nhập lại như trên (quyền mới chỉ có hiệu lực sau khi đăng nhập lại).

Nếu dòng nhắc đã là deploy@... thì không cần exit, chỉ cần kiểm tra docker ps như trên.

3.6 Đăng nhập bằng khoá SSH, tắt đăng nhập bằng mật khẩu

Mật khẩu SSH dễ bị dò. Bước này cho máy tính của bạn đăng nhập VPS bằng khoá SSH, rồi tắt hẳn đăng nhập bằng mật khẩu và đăng nhập root.

Ngồi trực tiếp trên mini PC và không bao giờ SSH từ máy khác: có thể bỏ qua bước này.

Trên máy tính của bạn (mở cửa sổ PowerShell/Terminal mới, không gõ trong cửa sổ đang kết nối VPS):

  • Windows (PowerShell):

    ssh-keygen -t ed25519

    Bấm Enter 3 lần (giữ mặc định). Sau đó chép khoá lên VPS (thay IP_VPS, nhập mật khẩu của deploy khi được hỏi):

    type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh deploy@IP_VPS "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
  • macOS (Terminal):

    ssh-keygen -t ed25519
    ssh-copy-id deploy@IP_VPS

Kiểm tra: mở thêm một cửa sổ mới, gõ ssh deploy@IP_VPS. Phải vào được VPS mà không hỏi mật khẩu VPS. Giữ nguyên cửa sổ cũ đang kết nối, phòng khi có lỗi.

Trên VPS (trong cửa sổ vừa vào được bằng khoá; sudo hỏi mật khẩu của deploy):

sudo tee /etc/ssh/sshd_config.d/00-ads-mcp-hardening.conf >/dev/null <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
EOF
sudo sshd -t && sudo systemctl reload ssh
sudo sshd -T | grep -Ei '^(passwordauthentication|permitrootlogin)'

Dòng cuối phải in ra passwordauthentication no và permitrootlogin no. Từ giờ chỉ đăng nhập bằng ssh deploy@IP_VPS từ máy tính đã có khoá.

WARNING

Mất khoá (đổi máy tính, cài lại Windows) làkhông SSH vào VPS được nữa. Khi đó dùng console web trong trang quản lý của nhà cung cấp VPS (mini PC: bàn phím và màn hình gắn trực tiếp) để đăng nhập deploy và thêm khoá mới. Nên sao lưu thư mục .ssh của máy tính ở nơi an toàn. Tuỳ chọn chống dò mật khẩu thêm: fail2ban (docs/deploy-vps.md mục 3.6).


Bước 4. Tải phần mềm về VPS

4.1 Tải mã nguồn

sudo mkdir -p /opt/ads-mcp && sudo chown deploy: /opt/ads-mcp
git clone https://github.com/schhung1822/nextgency-mcp-ads.git /opt/ads-mcp
  • Có thể được hỏi mật khẩu của deploy (do lệnh sudo): nhập mật khẩu đã đặt ở bước 3.1.

  • Username: nhập TEN_GITHUB = tên đăng nhập (username) GitHub của tài khoản đã tạo token ở bước 1. Xem username: đăng nhập GitHub → bấm avatar góc trên bên phải → dòng in đậm. Không nhập email.

  • Password: dán Token B ở bước 1.2 (không hiện ký tự), Enter. Không nhập mật khẩu GitHub, GitHub chỉ nhận token.

Token không được lưu trên VPS: mỗi lần git pull (khi cập nhật) sẽ hỏi lại Username và Password (Token B). Không chạy git config credential.helper store (lệnh đó lưu token thành chữ thường trên ổ đĩa).

Tuỳ chọn, đỡ phải dán lại nhiều lần trong 1 buổi làm việc: git config --global credential.helper 'cache --timeout=900' (chỉ nhớ token trong RAM 15 phút).

4.2 Đăng nhập kho image

Dán nguyên khối lệnh dưới đây (thay TEN_GITHUB); khi thấy dòng Dán Token A rồi Enter: thì dán Token A ở bước 1.1 (không hiện ký tự) rồi Enter:

cd /opt/ads-mcp
read -rsp "Dán Token A rồi Enter: " CR_PAT; echo
printf '%s' "$CR_PAT" | docker login ghcr.io -u TEN_GITHUB --password-stdin; unset CR_PAT

Thấy Login Succeeded là đúng (cảnh báo credentials are stored unencrypted là bình thường trên máy chủ Linux).


Bước 5. Chọn cách đưa web ra Internet

CAUTION

Tuyệt đối không dùng sub domain là ads.example.com vì sub domain ads dễ bị trình duyệt chặn gây setup lỗi. Trình chặn quảng cáo / phần mềm diệt virus chặn các địa chỉ bắt đầu bằng ads.: trang hiện ra nhưng mất giao diện, F12 báo ERR_ABORTED. Dùng sub domain đề xuất là mcp (ví dụ mcp.congty.vn).

Chọn một trong hai cách:

Cách A - Caddy tự cấp SSL

Cách B - Cloudflare Tunnel

Phù hợp

Đơn giản nhất, dùng được với mọi nhà cung cấp tên miền

Tên miền đã dùng Cloudflare; không muốn mở cổng nào trên VPS

Cần mở cổng

80, 443

Không

SSL

Tự động (Let's Encrypt)

Cloudflare lo

Cách nâng cao (Cloudflare proxy + chứng chỉ Origin, Nginx + Certbot): xem docs/deploy-vps.md.

Cách A - Caddy tự cấp SSL

Vào trang quản lý DNS của tên miền (nơi bạn mua tên miền, hoặc Cloudflare), thêm 1 bản ghi:

Loại (Type)

Tên (Name/Host)

Giá trị (Value/IP)

A

mcp

IP_VPS

  • Nếu dùng Cloudflare: để Proxy status = DNS only (đám mây xám).

  • Đợi 5-15 phút để DNS cập nhật. Kiểm tra trên VPS: getent hosts mcp.congty.vn phải ra đúng IP_VPS.

Sau đó làm tiếp bước 6, dùng --ssl auto.

Cách B - Cloudflare Tunnel

Tên miền phải đang quản lý trên Cloudflare.

  1. Đăng nhập https://one.dash.cloudflare.com → chọn tài khoản.

  2. Menu trái: Networks → Tunnels → Create a tunnel → chọn Cloudflared → Next.

  3. Tunnel name: gõ ads-mcp → Save tunnel.

  4. Màn hình Install and run a connector: chọn biểu tượng Docker. Bạn sẽ thấy một lệnh dạng: docker run cloudflare/cloudflared:latest tunnel --no-autoupdate run --token eyJhIjoi... → Chỉ sao chép phần token (chuỗi dài bắt đầu bằng eyJ sau chữ --token), lưu tạm lại. Không chạy lệnh docker run này. → bấm Next.

  5. Màn hình Route traffic / Public hostname:

    • Subdomain: mcp

    • Domain: chọn congty.vn

    • Service Type: HTTP

    • URL: caddy:80

    • Không mở Additional application settings.

    • Bấm Save / Complete setup.

    Nếu Cloudflare báo đã có bản ghi DNS mcp thì vào DNS xoá bản ghi cũ đó rồi lưu lại.

  6. Cấu hình thêm cho tên miền (trang quản lý tên miền trên https://dash.cloudflare.com):

    • SSL/TLS → Edge Certificates: bật Always Use HTTPS.

    • Security → Bots: tắt Bot Fight Mode (nếu bật, AI không gọi được MCP).

    • Caching → Cache Rules → Create rule: Field URI Path, Operator starts with, Value /mcp/ → Or → URI Path starts with /api/ → Cache eligibility: Bypass cache → Deploy.

Sau đó làm tiếp bước 6, dùng --ssl tunnel.


Bước 6. Tạo file cấu hình

6.1 Tạo file .env

File .env chứa mật khẩu cơ sở dữ liệu và khoá mã hoá, được tạo tự động với giá trị ngẫu nhiên.

Cách A:

cd /opt/ads-mcp
sh scripts/gen-secrets.sh --domain mcp.congty.vn --email it@congty.vn --ssl auto

Cách B (Cloudflare Tunnel):

cd /opt/ads-mcp
sh scripts/gen-secrets.sh --domain mcp.congty.vn --email it@congty.vn --ssl tunnel

Lần đầu chạy có thể mất 1-2 phút (tải công cụ tạo khoá). Chạy xong sẽ có file /opt/ads-mcp/.env.

6.2 Thêm token GitHub vào cấu hình

Để phần mềm tự kiểm tra và tải bản cập nhật. Dán nguyên khối lệnh dưới đây; khi thấy dòng Dán Token B rồi Enter: thì dán Token B ở bước 1.2 (không hiện ký tự) rồi Enter:

read -rsp "Dán Token B rồi Enter: " GH_TOKEN; echo
echo "UPDATE_GITHUB_TOKEN=$GH_TOKEN" >> .env; unset GH_TOKEN
echo "UPDATER_DOCKER_CONFIG=$HOME/.docker" >> .env
grep -cE "^UPDATE_GITHUB_TOKEN=(ghp_|github_pat_)" .env

Dòng cuối in ra 1 là đúng. In ra 0 nghĩa là chưa dán đúng token: mở nano .env, sửa dòng UPDATE_GITHUB_TOKEN= ở cuối file.

6.3 (Chỉ Cách B) Dán token Cloudflare Tunnel

nano .env

Trong trình soạn thảo nano:

  1. Dùng phím mũi tên tìm dòng TUNNEL_TOKEN=.

  2. Đưa con trỏ ra sau dấu = và dán token eyJ... đã lưu ở Cách B (chuột phải hoặc Cmd+V).

  3. Lưu: bấm Ctrl+O, rồi Enter. Thoát: bấm Ctrl+X.

6.4 Khoá quyền đọc file

chmod 600 .env

Bước 7. Khởi chạy

cd /opt/ads-mcp
docker compose pull
docker compose up -d --no-build
  • pull tải phần mềm về (vài phút lần đầu).

  • up -d chạy phần mềm ở chế độ nền.

Đợi khoảng 1 phút rồi kiểm tra:

docker compose ps -a

Kết quả đúng:

Dịch vụ

Trạng thái đúng

db

running (healthy)

migrate

exited (0) - chạy xong là tắt, bình thường

web

running (healthy)

worker, backup, updater, caddy

running

cloudflared (chỉ Cách B)

running (healthy)

Mở trình duyệt trên máy tính: https://mcp.congty.vn/api/health → thấy {"ok":true} là phần mềm đã chạy.

Cách A: lần đầu Caddy cần 30-60 giây để xin chứng chỉ SSL. Nếu trình duyệt báo lỗi chứng chỉ, đợi 1 phút rồi tải lại.


Bước 8. Tạo tài khoản Admin

Lấy mã cài đặt:

grep SETUP_TOKEN .env

Sao chép phần sau dấu =.

  1. Mở https://mcp.congty.vn/setup.

  2. Dán mã cài đặt, nhập tên, email, mật khẩu (tối thiểu 8 ký tự) → tạo tài khoản.

  3. Đăng nhập bằng email và mật khẩu vừa tạo.

  4. Khuyến nghị: vào Tài khoản → bật xác thực 2 lớp (2FA), rồi vào Cài đặt → Bảo mật → bật Bắt buộc 2FA cho quản trị viên.

Trang /setup tự khoá sau khi đã có tài khoản Admin.


Bước 9. Sao lưu file cấu hình

WARNING

Bước bắt buộc. File .env chứa khoá mã hoá (ENCRYPTION_KEYS). Mất file này là mất toàn bộ token quảng cáo đã lưu và không khôi phục được.

Hiện nội dung file:

cat .env

Bôi đen toàn bộ nội dung, sao chép, lưu vào trình quản lý mật khẩu (Bitwarden, 1Password...) hoặc ghi chú bảo mật. Không gửi qua chat/email, không để chung chỗ với file sao lưu dữ liệu.

Xong! Phần mềm đã chạy tại https://mcp.congty.vn.


Liên kết chính sách cho ứng dụng nền tảng quảng cáo

Ứng dụng nhà phát triển (Meta App Dashboard → App settings → Basic / Cài đặt ứng dụng → Thông tin cơ bản: URL chính sách quyền riêng tư, URL điều khoản dịch vụ, Xoá dữ liệu người dùng → URL hướng dẫn xoá dữ liệu; TikTok for Developers → thông tin app: Terms of Service URL, Privacy Policy URL; Google Cloud → màn hình đồng ý OAuth (Branding) cho Google Ads/YouTube: liên kết chính sách quyền riêng tư và điều khoản; OpenAI tương tự) cần các trang công khai. Mỗi bản cài đặt đã có sẵn 3 trang, không cần đăng nhập, tiếng Việt + bản tiếng Anh:

Trang

Địa chỉ

Chính sách quyền riêng tư

https://mcp.congty.vn/privacy

Điều khoản dịch vụ

https://mcp.congty.vn/terms

Hướng dẫn xoá dữ liệu

https://mcp.congty.vn/data-deletion

  1. Đăng nhập bằng Admin → Cài đặt → Thông tin pháp lý: nhập Tên đơn vị vận hành (công ty của bạn - bên chịu trách nhiệm về dữ liệu) và Email liên hệ quyền riêng tư → Lưu. Để trống thì trang dùng tên miền và ghi "quản trị viên hệ thống".

  2. Lấy liên kết: thanh bên trái, dưới tên tài khoản, khối Liên kết cho ứng dụng - bấm tên trang để mở, bấm biểu tượng sao chép để lấy địa chỉ đầy đủ (điện thoại: tab Menu).

  3. Dán các địa chỉ vào ứng dụng Meta, TikTok, Google Cloud (màn hình đồng ý OAuth) hoặc OpenAI.


Cập nhật phiên bản mới

Cách 1 - Trong web (khuyến nghị): khi có bản mới, Admin thấy thông báo ở menu tài khoản. Vào Cài đặt → Cập nhật → bấm Cập nhật lên vX.Y.Z → nhập lại mật khẩu. Hệ thống tự sao lưu dữ liệu, tải bản mới, kiểm tra chữ ký số của Nextgency (bản không có chữ ký bị từ chối), khởi động lại (web gián đoạn khoảng 1-2 phút) và tự quay về bản cũ nếu lỗi.

Ghi chú phát hành yêu cầu lấy cấu hình mới (git pull)? Chạy trước khi bấm Cập nhật (git hỏi Username và Password = Token B):

cd /opt/ads-mcp && git pull --ff-only && docker compose up -d --no-build

Cách 2 - Chạy lệnh (dùng khi ghi chú phát hành yêu cầu, hoặc nút Cập nhật không dùng được). Thay X.Y.Z bằng số phiên bản mới (không có chữ v):

cd /opt/ads-mcp
docker compose exec -T db pg_dump -U adsmcp -d adsmcp -Fc > backups/truoc-cap-nhat-$(date +%F).dump
git pull --ff-only
sed -i 's/^APP_VERSION=.*/APP_VERSION=X.Y.Z/' .env
docker compose pull
docker compose up -d --no-build

Sao lưu và khôi phục dữ liệu

Phần mềm tự sao lưu cơ sở dữ liệu mỗi ngày vào thư mục /opt/ads-mcp/backups, giữ 14 ngày. Nên định kỳ tải thư mục này về máy hoặc đồng bộ lên dịch vụ lưu trữ khác.

File sao lưu chứa email người dùng, mật khẩu đã băm và token quảng cáo đã mã hoá: giữ bí mật như file .env, mã hoá trước khi đưa lên dịch vụ lưu trữ (ví dụ rclone crypt, restic - xem docs/van-hanh.md) và không để chung chỗ với bản sao .env.

Xem danh sách bản sao lưu:

ls -lh /opt/ads-mcp/backups

Sao lưu ngay:

cd /opt/ads-mcp
docker compose exec backup sh -c 'pg_dump -Fc -f /backups/adsmcp_manual_$(date +%F_%H%M%S).dump'

Khôi phục từ một bản sao lưu (ghi đè dữ liệu hiện tại; thay TEN_FILE.dump bằng tên file trong thư mục backups):

cd /opt/ads-mcp
docker compose stop web worker updater
docker compose exec backup pg_restore --clean --if-exists -d adsmcp /backups/TEN_FILE.dump
docker compose up -d --no-build

Chuyển sang VPS mới: làm lại bước 2 → 5, chép file .env cũ vào /opt/ads-mcp/.env (không chạy lại bước 6.1), chép file sao lưu vào /opt/ads-mcp/backups/, chạy docker compose up -d --no-build db backup, rồi chạy lệnh khôi phục ở trên.


Các lệnh hay dùng

Luôn cd /opt/ads-mcp trước khi chạy:

Việc

Lệnh

Xem trạng thái

docker compose ps -a

Xem log web

docker compose logs --tail=100 web

Xem log tất cả (theo dõi liên tục, Ctrl+C để thoát)

docker compose logs -f

Khởi động lại

docker compose restart

Dừng phần mềm

docker compose stop

Chạy lại

docker compose up -d --no-build

Admin quên mật khẩu

docker compose run --rm web node dist/cli.mjs reset-password email@congty.vn

Admin mất 2FA

docker compose run --rm web node dist/cli.mjs reset-2fa email@congty.vn


Lỗi thường gặp

Hiện tượng

Cách xử lý

git clone / git pull báo Authentication failed / Repository not found

Sai Username, Token B sai/hết hạn (phải tích repo), hoặc tài khoản GitHub chưa được Nextgency cấp quyền. Kiểm tra lại bước 1.2 rồi chạy lại lệnh, dán đúng Token B khi được hỏi Password.

docker compose pull báo denied / unauthorized

Đăng nhập lại kho image bằng Token A còn hạn (chỉ tích read:packages): làm lại bước 4.2.

Mọi lệnh docker compose báo Thiếu APP_VERSION trong .env

nano .env, đặt dòng APP_VERSION= bằng phiên bản đang chạy (ví dụ APP_VERSION=1.0.2, không có chữ v; xem trang Releases trên GitHub), lưu rồi chạy lại lệnh.

permission denied ... docker.sock

sudo usermod -aG docker deploy, rồi exit và đăng nhập lại (ssh deploy@IP_VPS hoặc su - deploy) - xem bước 3.5.

Bước 3 báo Permission denied / Only root may add a user

Đang ở user thường: gõ sudo -i rồi chạy lại (xem bước 2).

ssh: Could not resolve hostname deploy

Gõ thiếu IP: dùng ssh deploy@IP_VPS, hoặc su - deploy nếu đang ngồi trên chính máy chủ.

Trang web hiện ra nhưng mất giao diện (chữ trắng đen, không màu), F12 báo ERR_ABORTED 499

Sub domain bắt đầu bằng ads. bị trình chặn quảng cáo/diệt virus chặn. Đổi sang mcp. (sửa Cloudflare/DNS + sed -i 's/ads\./mcp./g' .env rồi docker compose up -d --no-build). Thử thêm Ctrl+F5 hoặc cửa sổ ẩn danh.

migrate ở trạng thái exited (1)

Xem lỗi: docker compose logs migrate. Gửi nội dung lỗi cho Nextgency.

Cách A: trình duyệt báo lỗi chứng chỉ / không vào được

Kiểm tra bản ghi A đúng IP_VPS (getent hosts mcp.congty.vn), Cloudflare để đám mây xám, đã mở cổng 80/443 ở bước 3.4. Xem docker compose logs caddy.

Cách B: Cloudflare báo lỗi 1033

Tunnel chưa kết nối: kiểm tra TUNNEL_TOKEN trong .env, xem docker compose logs --tail=50 cloudflared.

Cách B: lỗi 502

Public hostname phải là HTTP + caddy:80.

Cách B: lỗi chuyển hướng quá nhiều lần

File .env không tạo bằng --ssl tunnel. Làm lại bước 6 với --ssl tunnel --force.

Trang Cập nhật báo "Chưa bật"

docker compose ps -a updater phải running. Kiểm tra .env có dòng COMPOSE_PROFILES=updater và UPDATER_DOCKER_CONFIG, rồi docker compose up -d --no-build.

Trang Cập nhật báo "Không tìm thấy bản phát hành nào"

Token B sai/hết hạn hoặc tài khoản GitHub mất quyền Read: tạo Token B mới (bước 1.2), sửa dòng UPDATE_GITHUB_TOKEN= trong .env, rồi docker compose up -d --no-build.

Cập nhật lỗi ở bước "tải image": không xác minh được chữ ký số

Máy chủ phải ra Internet được tới ghcr.io và Sigstore (*.sigstore.dev): kiểm tra tường lửa chiều ra rồi bấm Cập nhật lại. Bản đang chạy không bị ảnh hưởng. Không tự tắt bước kiểm tra chữ ký: hỏi Nextgency trước.

Admin bị khoá tài khoản

docker compose run --rm web node dist/cli.mjs unban email@congty.vn

AI báo lỗi 524 (Cách B)

Yêu cầu quá 125 giây: nhờ AI chia nhỏ (ít tài khoản hơn, khoảng ngày ngắn hơn).

Cần hỗ trợ: gửi cho Nextgency kết quả của docker compose ps -a và docker compose logs --tail=100 <tên dịch vụ lỗi>. Không gửi nội dung file .env.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      MCP server for managing Google Ads, Meta Ads, LinkedIn Ads, and TikTok Ads via AI. 210+ tools including account audits, wasted spend detection, and PMax insights.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to create, analyze, and optimize ad campaigns across Google Ads, Meta Ads, TikTok Ads, LinkedIn Ads, Amazon Ads, and ChatGPT Ads through natural language using 400+ tools.
      108
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Hosted remote MCP for Google Ads, Meta Ads (Facebook and Instagram), GA4 and Google Search Console. Connect Claude, ChatGPT, Cursor, Claude Code or Grok with a Google or Facebook login: audits, search terms, GAQL and Insights reports, keyword research, AI-referral traffic, and approved changes to budgets, bids and negatives. OAuth 2.1, no API keys, free.
      8,167
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants and agents to read analytics and manage advertising across Google Ads, Google Analytics 4, and Meta Ads through natural language, with preview-confirm guardrails and configurable account and budget limits.
      21
      MIT