Vnstock Logo

Cài đặt và kết nối

Thử nghiệm

Mục lục

Bản thử nghiệm, chưa phát hành chính thức

Trang này viết cho vnstock_mcp v1.0.0rc1, bản thử nghiệm. Tên hàm, tham số và cột dữ liệu có thể còn đổi trước ngày phát hành; khi cài, ghi rõ số phiên bản như ở trang Cài đặt. Bản đang phát hành chính thức là v0.4.0, xem tài liệu bản đó.

Cài thư viện

Tạo một môi trường ảo riêng cho thế hệ 6, rồi cài vnstock-mcp cùng các thư viện đi kèm:

Shell
python -m venv ~/.venv_vnstock6 && source ~/.venv_vnstock6/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages \
  "vnstock-mcp[quant]==1.0.0rc1" "vnstock==6.0.0rc3" "vnstock-oapi==0.1.0rc2"
vnstock-mcp --version
  • [quant] cài kèm vnstock_quant 1.0.0rc1 cho các tool tính toán và chạy thử chiến lược. Bỏ [quant] thì máy chủ chỉ có tool dữ liệu và tool nghiên cứu.
  • Cần đọc báo cáo tài chính dạng PDF thì thêm pdf: "vnstock-mcp[quant,pdf]==1.0.0rc1". Lưu bảng dạng Parquet thì thêm parquet.
  • Luôn ghi rõ số phiên bản. pip không tự chọn bản thử nghiệm; lệnh không ghi phiên bản sẽ không cài thế hệ 6.
Đừng cài đè lên môi trường thế hệ 5

Thế hệ 6 dùng chung tên gói vnstock với thế hệ 5. Cài vnstock-mcp 1.0.0rc1 vào môi trường đang chạy bản 0.5 sẽ thay luôn vnstock thế hệ 5 ở đó. Hãy dùng môi trường riêng như lệnh trên. Cách giữ hai bản song song: Chuyển từ bản 0.5.

Yêu cầu: Python 3.10 trở lên. Bản 1.0.0rc1 hiện chỉ có bản dựng sẵn cho macOS chip Apple (arm64); bản cho Windows và Linux chưa dựng.

Cất khoá nguồn

Thế hệ 6 truy xuất dữ liệu bằng khoá Open API do bạn đăng ký ở từng nguồn. Danh sách nguồn, loại khoá và nơi đăng ký: Cài đặt và khoá nguồn của vnstock 6.

Cất khoá vào keyring của hệ điều hành, gõ trong terminal:

Shell
vnstock keys set ssi      # thay ssi bằng nguồn bạn có khoá: dnse, tcbs, fhsc, fmp
Dùng keyring thay vì tệp .env

vnstock-oapi tìm khoá theo thứ tự: biến môi trường, tệp .env trong thư mục đang chạy, rồi keyring. Ứng dụng AI khởi chạy vnstock-mcp từ thư mục của chính ứng dụng, nên khoá để trong tệp .env của dự án thường không được thấy, và biến môi trường bạn export trong một cửa sổ terminal cũng không truyền sang. Keyring thì đọc được ở mọi nơi. Đừng dán khoá vào tệp cấu hình của ứng dụng AI hay vào cuộc trò chuyện.

Khoá không bao giờ đi qua vnstock-mcp: máy chủ chỉ hỏi thư viện nguồn nào có khoá, không đọc và không trả lại khoá. Thêm hay đổi khoá xong, khởi động lại ứng dụng AI để máy chủ dựng lại danh sách tool.

Tài khoản Vnstock (cấp quyền cho vnstock_quant) là khoá khác, dùng chung với thế hệ 5: vnstock login, kiểm bằng vnstock status. Chưa đăng nhập thì máy chủ chạy ở bản Cộng đồng.

Nối vào ứng dụng AI

vnstock-mcp --setup in cấu hình cho từng ứng dụng, với đường dẫn tuyệt đối tới lệnh vnstock-mcp trong môi trường ảo của bạn (ứng dụng AI không đọc PATH hay môi trường ảo đang kích hoạt):

Shell
vnstock-mcp --setup                    # liệt kê ứng dụng hỗ trợ
vnstock-mcp --setup claude-desktop     # in cấu hình, chưa ghi gì
vnstock-mcp --setup claude-desktop --write
Ứng dụngTên trong --setup--write làm gì
Claude Desktop (Chat, Cowork)claude-desktopGhi vào claude_desktop_config.json, sao lưu .bak, giữ máy chủ khác
ChatGPT desktop (chế độ Codex hoặc Work)chatgptChạy codex mcp add
Gemini TasksgeminiGhi vào ~/.gemini/settings.json
Claude Codeclaude-codeChạy claude mcp add --scope user: dùng được ở mọi dự án
Codex (CLI, tiện ích IDE)codexChạy codex mcp add
AntigravityantigravityGhi vào tệp cấu hình của ứng dụng
VS Code (Copilot agent)vscodeGhi .vscode/mcp.json của thư mục đang mở
CursorcursorGhi vào ~/.cursor/mcp.json, rồi bật trong Settings → MCP

Ghi xong, khởi động lại ứng dụng. Trợ lý sẽ thấy các tool reference_*, market_*, quant_*, research_*.

Kiểm máy

Shell
vnstock-mcp status      # phiên bản, cấp quyền, nguồn có khoá, số tool, ứng dụng đã nối
vnstock-mcp doctor      # môi trường, cấu hình, quyền đọc thư mục và một lời gọi dữ liệu thật
vnstock-mcp onboard     # quy tắc và việc tiếp theo, viết cho trợ lý AI đọc

status và onboard có --json. Khi một ứng dụng báo không chạy được máy chủ, doctor là bước đầu tiên: nó cho biết thư viện có import được không, sandbox của ứng dụng có đọc được thư mục cài không, và nguồn nào gọi được.

Giao diện tương tác

Gõ vnstock-mcp không kèm gì trong terminal thì mở giao diện tương tác: khung chào cho biết trạng thái máy, gõ help để xem lệnh, exit để thoát. Ứng dụng AI gọi đúng lệnh đó nhưng không có terminal, nên nhận máy chủ MCP như thường; cấu hình đã ghi không phải sửa.

HTTP trên máy

Mặc định máy chủ dùng stdio. Công cụ khác chạy trên cùng máy cần gọi qua HTTP thì:

Shell
VNSTOCK_MCP_TOKEN=<chuỗi bí mật tuỳ chọn> vnstock-mcp serve -t streamable-http --port 8000

Máy chủ chỉ nhận địa chỉ loopback (127.0.0.1, ::1, localhost); --host khác bị từ chối. Đặt token bằng biến môi trường thay vì --token, vì tham số dòng lệnh lộ trong danh sách tiến trình. Mặc định giới hạn 120 yêu cầu mỗi phút (--rate-limit).

Cập nhật và hạn dùng

Mỗi bản phát hành có hạn dùng do vnstocks.com ký: 30 ngày với bản thử nghiệm như 1.0.0rc1, 365 ngày với bản chính thức. Gần hết hạn, máy chủ nhắc một lần; hết hạn thì mọi tool báo lỗi ReleaseExpiredError kèm hướng dẫn của máy chủ. Cập nhật bằng đúng lệnh cài ở trên với số phiên bản mới.

Tags

vnstock_mcp
thế hệ 6
cài đặt