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

Tổng quan

Trang này hướng dẫn bạn cài đặt thư viện vnstock-mcp và cấu hình kết nối vào các công cụ Trợ lý AI thế hệ mới như Claude Code, ChatGPT Codex, Antigravity, Claude Desktop, ChatGPT Desktop và Gemini Spark.

Yêu cầu môi trường

• Hệ điều hành: macOS (Apple Silicon hoặc Intel), Linux x86_64, hoặc Windows 10/11 64-bit.
• Python: Phiên bản >= 3.10 (khuyên dùng Python 3.11 hoặc 3.12 trong môi trường ảo .venv).
• Thư viện hệ sinh thái: Cài đặt vnstock thế hệ 5 (và gói bổ trợ vnstock_quant nếu bạn dùng các tính năng định lượng).

Cài đặt thư viện

Bạn có thể cài đặt vnstock-mcp từ kho phân phối gói chính thức:

pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock vnstock-mcp

Sau khi cài đặt, kiểm tra đường dẫn thực thi của tệp dòng lệnh:

which vnstock-mcp
# Đầu ra mẫu trên macOS/Linux: /Users/mrthinh/.venv/bin/vnstock-mcp
# Đầu ra mẫu trên Windows (lệnh 'where'): C:\Users\mrthinh\.venv\Scripts\vnstock-mcp.exe

Chẩn đoán trạng thái hệ thống

Trước khi kết nối vào Trợ lý AI, bạn có thể chạy công cụ chẩn đoán tích hợp sẵn để kiểm tra trạng thái các thành phần (Python, Rust Core, cấp tài khoản và thư mục nghiên cứu):

vnstock-mcp --doctor

=================================================================
  vnstock-mcp v0.4.0 · Chẩn Đoán Hệ Thống (System Doctor)
=================================================================
[✓] Python Runtime: 3.11.8 (~/.venv/bin/python)
[✓] Rust Core (_native): Hoạt động bình thường
    - Cấp tài khoản: GOLDEN (Nhà tài trợ)
    - Hạn dùng bản phát hành: Hợp lệ
[✓] vnstock lõi: v5.0.0
[✓] vnstock_quant: v0.1.3
[✓] Thư mục nghiên cứu: ~/vnstock_research (Quyền ghi: OK)
=================================================================
✓ Toàn bộ hệ thống sẵn sàng hoạt động với Trợ lý AI!

Kết nối vào các Trợ lý AI

vnstock-mcp giao tiếp qua chuẩn stdio của giao thức MCP (Model Context Protocol). Trợ lý AI sẽ khởi động tiến trình nền khi bắt đầu phiên làm việc.

Nhóm 1: Chế độ Code (Coding & CLI Agents)

1. Kết nối với Claude Code (CLI)

Chạy lệnh thêm MCP server trực tiếp trong terminal:

# Trên macOS & Linux: Biến môi trường $HOME tự động trỏ về thư mục cá nhân của bạn
claude mcp add vnstock-mcp "$HOME/.venv/bin/vnstock-mcp"

Với người dùng Windows PowerShell:

claude mcp add vnstock-mcp "$env:USERPROFILE\.venv\Scripts\vnstock-mcp.exe"

Kiểm tra trạng thái kết nối:

claude mcp list

2. Kết nối với ChatGPT Codex (CLI / Code)

Thêm cấu hình vào tệp ~/.codex/config.json:

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "~/.venv/bin/vnstock-mcp",
      "args": [],
      "env": {
        "VNSTOCK_RESEARCH_DIR": "~/vnstock_research",
        "VNSTOCK_MCP_PROFILE": "full"
      }
    }
  }
}

3. Kết nối với Antigravity (Google Agentic IDE)

Thêm cấu hình vào tệp ~/.gemini/antigravity-ide/mcp_config.json hoặc .agents/mcp_config.json trong dự án của bạn:

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "~/.venv/bin/vnstock-mcp",
      "args": [],
      "env": {
        "VNSTOCK_RESEARCH_DIR": "~/vnstock_research",
        "VNSTOCK_MCP_PROFILE": "full"
      }
    }
  }
}

Nhóm 2: Chế độ App Desktop (Desktop Applications)

4. Kết nối với Claude Desktop

Mở tệp cấu hình của Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Thêm cấu hình máy chủ vnstock-mcp:

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "~/.venv/bin/vnstock-mcp",
      "args": [],
      "env": {
        "VNSTOCK_RESEARCH_DIR": "~/vnstock_research"
      }
    }
  }
}

Sau khi khởi động lại Claude Desktop, biểu tượng công cụ (hình chiếc búa) sẽ hiển thị danh sách các công cụ nghiên cứu chứng khoán khả dụng.

5. Kết nối với ChatGPT Desktop & Gemini Spark

• Với ChatGPT Desktop: Thêm cấu hình trên vào mục Advanced Settings / Developer của ứng dụng.
• Với Gemini Spark: Mở tệp ~/.gemini/spark/mcp.json và cấu hình tương tự.

Các biến môi trường tùy chỉnh

Bạn có thể tùy chỉnh hành vi của vnstock-mcp thông qua các biến môi trường: