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

Tổng quan

Trang này hướng dẫn bạn cài đặt vnstock-mcp và cấu hình kết nối chuẩn 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 dưới quyền tài khoản Cộng đồng (miễn phí cho cá nhân, học tập và nghiên cứu).

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

• Hệ điều hành: macOS (Apple Silicon hoặc Intel), Windows 10/11 64-bit, hoặc Linux x86_64.
• 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: Cài đặt gói vnstock và vnstock-mcp.

2. Cài đặt thư viện

Bạn có thể cài đặt vnstock-mcp trực tiếp qua pip:

# Cài đặt hoặc cập nhật phiên bản mới nhất
pip install -U vnstock vnstock-mcp

Sau khi cài đặt xong, kiểm tra tệp thực thi vnstock-mcp:

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

3. Kiểm tra trạng thái cấp tài khoản

Chạy lệnh kiểm tra tính toàn vẹn và quyền tài khoản của bạn:

vnstock-mcp --status

Đầu ra mẫu cho tài khoản Cộng đồng:

============================================================
              Vnstock MCP (Local) Research Harness
============================================================
Python Version      : 3.11.8
FastMCP Engine      : Native Rust Core (Gen 5)
Account Tier        : FREE (Bản Cộng đồng)
Active Tools Count  : 26 tools enabled (Tool Filtering active)
Daily Quant Trial   : 30 / 30 requests available
Data Journal Path   : ~/.vnstock/mcp_research/
============================================================
STATUS: OK - Ready for AI Agent integration.

4. Cấu hình kết nối vào Trợ lý AI

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

A. 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"

B. 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": []
    }
  }
}

C. 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:

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

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

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

Mở file 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ủ:

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

Khởi động lại Claude Desktop để máy chủ nhận diện 26 công cụ cơ sở.

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

• Với ChatGPT Desktop: Vào mục Cài đặt nâng cao (Advanced / Developer Settings) hoặc dán cấu hình trên vào tệp thiết lập MCP của ứng dụng.
• Với Gemini Spark: Thêm khối mcpServers tương tự vào tệp ~/.gemini/spark/mcp.json.�ể máy chủ nhận diện 26 công cụ.

C. 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"

D. Kết nối với Windsurf

Mở file ~/.codeium/windsurf/mcp_config.json và cấu hình:

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

5. Thử nghiệm câu lệnh đầu tiên

Sau khi kết nối thành công, bạn mở cửa sổ chat với Trợ lý AI và gửi các câu hỏi mẫu sau:

Kiểm tra công cụ

"Chào bạn, hãy kiểm tra danh sách công cụ Vnstock MCP bạn đang có và báo cho tôi biết cấp tài khoản hiện tại."

Tra cứu cổ phiếu FPT

"Hãy dùng Vnstock MCP để tra cứu hồ sơ doanh nghiệp FPT và lấy Báo cáo kết quả kinh doanh 4 quý gần nhất."

Dùng thử tính toán kỹ thuật (Quant Trial)

"Dùng công cụ quant_ta_basic để tính chỉ số RSI và MACD cho cổ phiếu HPG."

Trợ lý AI sẽ tự động kích hoạt công cụ phù hợp, hiển thị bảng kết quả rõ ràng và thông báo số lượt dùng thử còn lại trong ngày.

Tiếp theo

• Tìm hiểu chi tiết Phân quyền và lượt dùng thử của bản Cộng đồng.
• Xem Danh mục 26 Công cụ để khai thác tối đa sức mạnh của hệ thống.