VN Stock API MCP Server

MCP server để tìm kiếm và truy cập API từ các công ty chứng khoán Việt Nam: VNDirect, FireAnt, và SSI.

Tính năng

• Tìm kiếm API documentation từ VNDirect, FireAnt, và SSI
• Lấy thông tin về API endpoints
• Truy cập documentation URLs
• Lấy giá cổ phiếu real-time từ FireAnt (get_stock_price_fireant)
• Liệt kê tất cả mã cổ phiếu Việt Nam (list_vn_stocks) - tương tự list_assets trong coincap-mcp
• Lấy tin tức thị trường chứng khoán từ CafeF (get_cafef_market_news) - sử dụng Firecrawl API để scrape tin tức
• Phân tích mô hình nến Doji (analyze_doji_pattern) - phân tích kỹ thuật để phát hiện tín hiệu đảo chiều

Cài đặt

Cách 1: Clone từ GitHub (Khuyến nghị)

# Clone repository
git clone https://github.com/Long0308/vn-stock-api-mcp.git
cd vn-stock-api-mcp

# Cài đặt dependencies và build
npm install
npm run build

Cách 2: Sử dụng trực tiếp từ GitHub (đã có sẵn dist/)

Nếu bạn chỉ muốn sử dụng mà không cần phát triển, bạn có thể clone và sử dụng trực tiếp:

# Clone repository
git clone https://github.com/Long0308/vn-stock-api-mcp.git
cd vn-stock-api-mcp

# Chỉ cần cài đặt dependencies (dist/ đã có sẵn)
npm install

Cấu hình trong mcp.json

Cấu hình với đường dẫn local (sau khi clone)

Cấu hình cơ bản (không có Firecrawl API):

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\vn-stock-api-mcp\\dist\\index.js"
      ]
    }
  }
}

Cấu hình đầy đủ (có Firecrawl API để sử dụng tính năng get_cafef_market_news):

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\vn-stock-api-mcp\\dist\\index.js"
      ],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key-here"
      }
    }
  }
}

Cấu hình với đường dẫn tương đối

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": [
        "~/vn-stock-api-mcp/dist/index.js"
      ],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key-here"
      }
    }
  }
}

Lưu ý:

• Thay C:\\path\\to\\vn-stock-api-mcp hoặc ~/vn-stock-api-mcp bằng đường dẫn thực tế đến thư mục bạn đã clone.
• Thay "your-firecrawl-api-key-here" bằng API key thực tế của bạn từ firecrawl.dev (chỉ cần nếu muốn sử dụng tính năng get_cafef_market_news).
• Nếu không có Firecrawl API key, các tool khác vẫn hoạt động bình thường, chỉ có get_cafef_market_news sẽ sử dụng phương pháp fallback.

Tools có sẵn

1. search_vn_stock_api

Tìm kiếm API documentation từ các nhà cung cấp.

Parameters:

• provider: "vndirect" | "fireant" | "ssi" | "all"
• query (optional): Từ khóa tìm kiếm

2. get_api_endpoints

Lấy danh sách API endpoints cho một nhà cung cấp.

Parameters:

• provider: "vndirect" | "fireant" | "ssi"
• category (optional): Lọc theo category

3. get_api_documentation_urls

Lấy URLs của API documentation.

Parameters:

• provider: "vndirect" | "fireant" | "ssi" | "all"

4. get_stock_price_fireant

Lấy giá cổ phiếu real-time từ FireAnt API. Hỗ trợ lấy giá cho một hoặc nhiều mã cổ phiếu cùng lúc.

Parameters:

• symbol: Mã cổ phiếu (ví dụ: "VIC", "VNM", "VCB"). Có thể truyền nhiều mã cách nhau bằng dấu phẩy (ví dụ: "VIC,VNM,VCB")

Ví dụ sử dụng:

{
  "symbol": "VIC"
}

hoặc nhiều mã:

{
  "symbol": "VIC,VNM,VCB"
}

Lưu ý:

• FireAnt API có thể yêu cầu authentication. Nếu API không hoạt động, tool sẽ cung cấp URL web để truy cập thông tin trên FireAnt website.
• Để lấy dữ liệu real-time tốt hơn, có thể sử dụng kết hợp với Firecrawl MCP server để scrape từ website FireAnt.

5. list_vn_stocks

Liệt kê tất cả các mã cổ phiếu Việt Nam có sẵn. Tương tự như list_assets trong coincap-mcp, tool này trả về danh sách đầy đủ các mã cổ phiếu được giao dịch trên các sàn chứng khoán Việt Nam (HOSE, HNX, UPCOM).

Parameters:

• exchange (optional): Lọc theo sàn giao dịch - "HOSE" (Sàn Hồ Chí Minh), "HNX" (Sàn Hà Nội), "UPCOM" (Thị trường UPCOM), hoặc "all" để lấy tất cả (mặc định: "all")
• search (optional): Từ khóa tìm kiếm để lọc theo mã cổ phiếu hoặc tên công ty

Ví dụ sử dụng:

Liệt kê tất cả mã cổ phiếu:

{}

Lọc theo sàn HOSE:

{
  "exchange": "HOSE"
}

Tìm kiếm mã cổ phiếu:

{
  "search": "VIC"
}

Kết hợp filter và search:

{
  "exchange": "HOSE",
  "search": "bank"
}

Lưu ý:

• Tool sẽ cố gắng lấy danh sách từ FireAnt API trước, nếu không thành công sẽ sử dụng danh sách tĩnh các mã cổ phiếu phổ biến.
• Danh sách bao gồm các mã cổ phiếu lớn và phổ biến trên thị trường Việt Nam.
• Để lấy thông tin chi tiết và giá real-time, sử dụng get_stock_price_fireant với mã cổ phiếu cụ thể.

6. get_cafef_market_news

Lấy tin tức thị trường chứng khoán mới nhất từ CafeF (cafef.vn). Tool này sử dụng Firecrawl API để scrape và trả về tin tức, phân tích, và cập nhật thị trường từ trang tin tài chính hàng đầu Việt Nam.

Parameters:

• limit (optional): Số lượng bài viết tối đa cần trả về (mặc định: 20, tối đa: 100)
• search (optional): Từ khóa tìm kiếm để lọc tin tức (ví dụ: "VIC", "VN-Index", "ngân hàng")
• format (optional): Định dạng đầu ra - "markdown" (văn bản có định dạng), "json" (dữ liệu có cấu trúc), hoặc "text" (văn bản thuần). Mặc định: "markdown"

Ví dụ sử dụng:

Lấy 20 tin tức mới nhất:

{}

Lấy 10 tin tức về VIC:

{
  "limit": 10,
  "search": "VIC"
}

Lấy tin tức dạng JSON:

{
  "limit": 20,
  "format": "json"
}

Tìm kiếm tin tức về ngân hàng:

{
  "search": "ngân hàng",
  "limit": 15
}

Lưu ý:

• Tool sử dụng Firecrawl API để scrape dữ liệu từ cafef.vn.
• Để sử dụng Firecrawl API, bạn cần tự đăng ký và lấy API key của riêng bạn từ firecrawl.dev.
• Nếu không có Firecrawl API key, tool sẽ sử dụng phương pháp fallback với HTML parsing cơ bản (kết quả có thể kém chính xác hơn).
• Để có kết quả tốt nhất, nên sử dụng Firecrawl API key của bạn.

Cách lấy Firecrawl API Key:

1. Truy cập https://firecrawl.dev
2. Đăng ký tài khoản miễn phí hoặc đăng nhập
3. Vào Dashboard và lấy API key của bạn
4. Copy API key và thêm vào cấu hình mcp.json như hướng dẫn bên dưới

Cấu hình Firecrawl API Key trong mcp.json:

Thêm env với FIRECRAWL_API_KEY vào cấu hình của vn-stock-api-mcp:

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\vn-stock-api-mcp\\dist\\index.js"],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key-here"
      }
    }
  }
}

⚠️ QUAN TRỌNG:

• Thay "your-firecrawl-api-key-here" bằng API key thực tế của bạn từ firecrawl.dev
• KHÔNG chia sẻ API key của bạn công khai
• KHÔNG commit API key vào Git repository

7. analyze_doji_pattern

Phân tích mô hình nến Doji trong biểu đồ giá cổ phiếu. Mô hình Doji cho thấy sự không chắc chắn của thị trường và tiềm năng đảo chiều xu hướng. Tool này phát hiện các loại Doji khác nhau bao gồm Standard Doji, Long-legged Doji, Dragonfly Doji, Gravestone Doji, và Four Price Doji.

Parameters:

• symbol (required): Mã cổ phiếu cần phân tích (ví dụ: "VIC", "VNM", "VCB")
• period (optional): Chu kỳ thời gian phân tích - "1D" (ngày), "1W" (tuần), "1M" (tháng). Mặc định: "1D"
• days (optional): Số ngày để phân tích (mặc định: 30, tối đa: 100). Dùng để phát hiện mô hình Doji trong dữ liệu lịch sử
• threshold (optional): Ngưỡng phát hiện Doji theo phần trăm của khoảng giá (mặc định: 0.1 = 0.1%). Giá trị thấp hơn sẽ phát hiện nhiều mô hình Doji hơn

Ví dụ sử dụng:

Phân tích Doji cho VIC (30 ngày gần nhất):

{
  "symbol": "VIC"
}

Phân tích Doji với chu kỳ tuần:

{
  "symbol": "VIC",
  "period": "1W",
  "days": 60
}

Phân tích với ngưỡng tùy chỉnh:

{
  "symbol": "VNM",
  "threshold": 0.05,
  "days": 50
}

Các loại mô hình Doji được phát hiện:

1. Standard Doji: Giá mở và giá đóng gần như bằng nhau với bóng nến ở cả hai phía

   • Ý nghĩa: Thị trường không chắc chắn, có thể đảo chiều xu hướng

2. Long-legged Doji: Thân nến nhỏ với bóng trên và bóng dưới rất dài

   • Ý nghĩa: Biến động cao và không chắc chắn mạnh, tiềm năng đảo chiều

3. Dragonfly Doji: Giá mở và giá đóng gần mức cao nhất, với bóng dưới dài

   • Ý nghĩa: Tín hiệu tăng giá, đặc biệt sau xu hướng giảm

4. Gravestone Doji: Giá mở và giá đóng gần mức thấp nhất, với bóng trên dài

   • Ý nghĩa: Tín hiệu giảm giá, đặc biệt sau xu hướng tăng

5. Four Price Doji: Giá mở = giá cao = giá thấp = giá đóng (rất hiếm)

   • Ý nghĩa: Không chắc chắn cực mạnh, xuất hiện rất hiếm

Lưu ý:

• Tool cần dữ liệu OHLC (Open, High, Low, Close) từ FireAnt API hoặc nguồn khác
• Nếu FireAnt API không khả dụng, tool sẽ cung cấp hướng dẫn sử dụng Firecrawl để scrape dữ liệu
• Mô hình Doji chỉ cho thấy sự không chắc chắn của thị trường, nên kết hợp với các chỉ báo kỹ thuật khác để đưa ra quyết định đầu tư
• Phân tích kỹ thuật không đảm bảo kết quả đầu tư, chỉ mang tính chất tham khảo

Các nhà cung cấp được hỗ trợ

VNDirect

• Open API
• D-Stock Data API
• Documentation: https://www.vndirect.com.vn/san-pham-to-chuc/apis-white-labeling/

FireAnt

• FireAnt API
• Base URL: https://api.fireant.vn
• Documentation: https://api.fireant.vn/

SSI

• FastConnect Trading API
• FastConnect Data API
• Documentation: https://guide.ssi.com.vn/ssi-products/tieng-viet/fastconnect-trading/danh-sach-cac-api

Development

npm run dev  # Watch mode
npm run build  # Build
npm start  # Run server

License

MIT