MCP Server

Model Context Protocol server cho vnstock-js — tích hợp Claude với dữ liệu chứng khoán Việt

MCP (Model Context Protocol) là tiêu chuẩn kết nối cho phép Claude và các AI models khác tương tác với dữ liệu và tools thực tế. vnstock-js MCP server cung cấp truy cập trực tiếp vào dữ liệu chứng khoán Việt Nam từ Claude Desktop, Claude Code, Cursor, và các ứng dụng hỗ trợ MCP khác.

Tại Sao MCP?

Trước đây, để Claude phân tích chứng khoán Việt, bạn cần:

Viết API wrapper riêng
Deploy server
Cấu hình API keys, authentication
Duy trì độc lập

Với MCP, Claude kết nối trực tiếp với vnstock-js thông qua stdio, không cần setup phức tạp. Một cấu hình, dùng ở mọi nơi.

Lợi ích:

🔌 Kết nối native với Claude Desktop, Claude Code, Cursor
🔐 Không expose public API, chạy local
⚡ Zero latency communication (stdio vs HTTP)
📱 Cùng config, dùng ở desktop, web, headless

Bắt Đầu Nhanh

Yêu Cầu

Node.js 16+
vnstock-js đã installed
```
npm install vnstock-js
```
Claude Desktop hoặc Claude Code (hoặc Cursor)

MCP SDK (@modelcontextprotocol/sdk) đã bao gồm trong vnstock-js — không cần cài thêm

Claude Desktop Setup

Tìm và mở file cấu hình Claude Desktop:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Thêm vnstock-js MCP server vào mcpServers:

{
  "mcpServers": {
    "vnstock-js": {
      "command": "npx",
      "args": ["-y", "vnstock-js", "mcp"]
    }
  }
}

Restart Claude Desktop. Lúc này Claude sẽ có quyền dùng 13 tools của vnstock-js.

Claude Code Setup

Trong Claude Code, dùng lệnh:

claude mcp add --scope user vnstock-js npx -y vnstock-js mcp

Verify:

claude mcp list
# Expected: vnstock-js: ... ✓ Connected

Hoặc cấu hình trong .claude/settings.local.json:

{
  "mcpServers": {
    "vnstock-js": {
      "command": "npx",
      "args": ["-y", "vnstock-js", "mcp"]
    }
  }
}

Cursor Setup

Tương tự Claude Code, thêm vào Cursor settings hoặc dùng MCP command line.

Xác Minh

Sau khi cấu hình, mở Claude và gõ:

Lấy giá hiện tại của VCB

Nếu Claude trả lời với dữ liệu VCB, MCP server đã kết nối thành công ✓

Tools Tham Khảo

Quote - Giá Cổ Phiếu Hiện Tại

Lấy giá khớp, thay đổi %, khối lượng, giá trần/sàn của một cổ phiếu.

Input:

symbol: string  // Mã cổ phiếu, ví dụ "VCB", "FPT"

Output:

{
  "symbol": "VCB",
  "matchingPrice": 105.2,
  "change": 1.2,
  "changePercent": 1.15,
  "volume": 15234500,
  "ceiling": 107.3,
  "floor": 103.1,
  "reference": 104.0
}

Ví dụ Claude prompt:

VCB giá bao nhiêu? Tăng hay giảm so với hôm qua?

History - Lịch Sử Giá

Lấy lịch sử giá (Open, High, Low, Close, Volume) trong khoảng thời gian.

Input:

symbol: string      // Mã cổ phiếu
from?: string       // YYYY-MM-DD, mặc định 30 ngày trước
to?: string         // YYYY-MM-DD, mặc định hôm nay
limit?: number      // Số phiên tối đa, mặc định 30

Output:

{
  "symbol": "VCB",
  "data": [
    {
      "date": "2026-05-23",
      "open": 104.0,
      "high": 105.5,
      "low": 103.8,
      "close": 105.2,
      "volume": 15234500
    }
  ]
}

Ví dụ Claude prompt:

Vẽ biểu đồ giá VCB 30 ngày qua. Xu hướng là tăng hay giảm?

Company - Thông Tin Công Ty

Lấy tên đầy đủ, ngành, sàn niêm yết của một cổ phiếu.

Input:

symbol: string  // Mã cổ phiếu

Output:

{
  "symbol": "VCB",
  "name": "Ngân Hàng Thương Mại Cổ Phần Vietcombank",
  "industry": "Ngân Hàng",
  "exchange": "HOSE"
}

Ví dụ Claude prompt:

VCB là công ty gì? Hoạt động ngành nào?

Dividends - Cổ Tức (v1.4.2+)

Lấy lịch sử & lịch chia cổ tức (tiền mặt + cổ phiếu): loại cổ tức, tỉ lệ/giá trị, ngày giao dịch không hưởng quyền (GDKHQ), ngày chốt danh sách.

Tool: get_dividends

Input:

symbol: string  // Mã cổ phiếu

Output: mảng CorporateEvent đã lọc cổ tức, mỗi phần tử gồm eventType, ratio, value, exRightDate, recordDate.

Ví dụ Claude prompt:

ACB chia cổ tức khi nào? Tỉ lệ bao nhiêu?

Corporate Events - Sự Kiện Doanh Nghiệp (v1.4.2+)

Lấy tất cả sự kiện doanh nghiệp: cổ tức, ĐHCĐ, phát hành thêm, niêm yết, giao dịch nội bộ.

Tool: get_corporate_events

Input:

symbol: string  // Mã cổ phiếu

Ví dụ Claude prompt:

HPG có sự kiện gì sắp tới?

Trading - Dữ Liệu Giao Dịch

Lấy thông tin giao dịch chi tiết: bid/ask, khối lượng mua/bán, giá trung bình.

Input:

symbol: string  // Mã cổ phiếu

Output:

{
  "symbol": "VCB",
  "buyPrice": 105.1,
  "buyVolume": 524000,
  "sellPrice": 105.2,
  "sellVolume": 478000,
  "totalVolume": 15234500,
  "averagePrice": 104.98
}

Ví dụ Claude prompt:

Giá bid/ask của FPT bây giờ là bao nhiêu?

Listing - Danh Sách Cổ Phiếu

Lấy danh sách tất cả cổ phiếu trên một sàn (HOSE, HNX, UPCOM).

Input:

exchange?: string  // "HOSE", "HNX", "UPCOM" (mặc định: tất cả)
limit?: number     // Số mã tối đa, mặc định 100

Output:

{
  "symbols": ["VCB", "FPT", "MBB", ...],
  "total": 403
}

Ví dụ Claude prompt:

Có bao nhiêu cổ phiếu trên HOSE?

Indicators - Chỉ Báo Kỹ Thuật

Tính toán MACD, Bollinger Bands, ATR cho một cổ phiếu.

Input:

symbol: string          // Mã cổ phiếu
indicator: string       // "macd" | "bollinger" | "atr"
period?: number         // Chu kỳ, mặc định 20/12
lookback?: number       // Số phiên lịch sử, mặc định 100

Output (MACD):

{
  "indicator": "macd",
  "symbol": "VCB",
  "data": [
    {
      "date": "2026-05-23",
      "macd": 0.45,
      "signal": 0.38,
      "histogram": 0.07
    }
  ]
}

Ví dụ Claude prompt:

Tính MACD cho VCB. Tín hiệu bullish hay bearish?

AI Context - Ngữ Cảnh AI

Lấy phân tích kỹ thuật tích hợp: trend, indicators, support/resistance, volume signal.

Input:

symbol: string      // Mã cổ phiếu
lookback?: number   // Số phiên, mặc định 200

Output:

{
  "symbol": "VCB",
  "trend": "bullish",
  "indicators": {
    "rsi": 65.2,
    "macd": { "signal": "bullish", "histogram": 0.07 },
    "sma20": 104.5,
    "sma50": 103.2,
    "sma200": 102.1
  },
  "support": 104.0,
  "resistance": 106.5,
  "volumeSignal": "strong",
  "priceChange": { "1d": 1.15, "7d": 2.5, "30d": 5.2 }
}

Ví dụ Claude prompt:

Phân tích kỹ thuật VCB. Nên mua hay bán?

Quick Quote - Giá Nhanh

Lấy giá của nhiều cổ phiếu cùng lúc (shorthand cho multiple quote calls).

Input:

symbols: string[]  // Mảng mã cổ phiếu, ví dụ ["VCB", "FPT", "MBB"]

Output:

{
  "data": [
    { "symbol": "VCB", "price": 105.2, "change": 1.15 },
    { "symbol": "FPT", "price": 89.5, "change": -0.5 },
    { "symbol": "MBB", "price": 26.3, "change": 2.1 }
  ]
}

Ví dụ Claude prompt:

So sánh giá VCB, FPT, MBB

Top Movers - Top Tăng/Giảm

Lấy top 10 cổ phiếu tăng mạnh và giảm mạnh hôm nay.

Input:

limit?: number  // Số mã mỗi bên, mặc định 10

Output:

{
  "gainers": [
    { "symbol": "AAA", "price": 10.5, "change": 3.2 },
    { "symbol": "BBB", "price": 20.1, "change": 2.8 }
  ],
  "losers": [
    { "symbol": "CCC", "price": 15.2, "change": -2.5 },
    { "symbol": "DDD", "price": 8.9, "change": -1.9 }
  ]
}

Ví dụ Claude prompt:

Hôm nay cổ phiếu nào tăng mạnh nhất?

Compare Symbols - So Sánh Cổ Phiếu

So sánh side-by-side giá, thay đổi %, RSI, volume signal của nhiều cổ phiếu.

Input:

symbols: string[]  // Mảng mã cổ phiếu

Output:

{
  "comparison": [
    {
      "symbol": "VCB",
      "price": 105.2,
      "change%": 1.15,
      "rsi": 65.2,
      "volumeSignal": "strong"
    },
    {
      "symbol": "MBB",
      "price": 26.3,
      "change%": 2.1,
      "rsi": 58.5,
      "volumeSignal": "normal"
    }
  ]
}

Ví dụ Claude prompt:

So sánh VCB, MBB, TCB. Cái nào tốt nhất để đầu tư?

Watchlist - Theo Dõi Danh Mục

CRUD (Create, Read, Update, Delete) cho danh mục theo dõi. Dữ liệu lưu tại ~/.vnstock-js/watchlist.json.

Input (Add):

action: "add"
name: string       // Tên danh mục, ví dụ "Tech Stocks"
symbol: string     // Mã cổ phiếu

Input (List):

action: "list"

Output:

{
  "watchlists": [
    {
      "name": "Tech Stocks",
      "symbols": ["FPT", "VNM", "DIG"],
      "createdAt": "2026-05-23T10:30:00Z"
    }
  ]
}

Ví dụ Claude prompt:

Thêm VCB vào danh mục "Ngân Hàng" của tôi
Hiển thị danh mục theo dõi của tôi

Kiến Trúc MCP Server

Protocol Flow

Claude              MCP Transport       vnstock-js Server       VCI API
   |                     |                    |                    |
   |--- Initialize ----->|                    |                    |
   |                     |--- Start Process -->|                    |
   |                     |                    |-- Connection OK ---|
   |                     |<--- Ready ---------|                    |
   |                     |                    |                    |
   |--- List Tools ----->|                    |                    |
   |                     |-- list_tools ----->|                    |
   |<----- Tools List ----|<-- Tool Schema ---|                    |
   |                     |                    |                    |
   |--- Call Tool ------>|                    |                    |
   | (quote, VCB)        |--- call_tool ----->|                    |
   |                     |                    |--- Fetch Data ---->|
   |                     |                    |<---- Response -----|
   |                     |<---- Result -------|                    |
   |<---- Response ------|                    |                    |

Thành Phần Chính

1. Server Initialization

vnstock-js khởi tạo MCP Server instance với stdio transport
Đăng ký 13 tools và schema của chúng

2. Transport Layer

stdio: stdin (request từ Claude) ↔ stdout (response)
JSON-RPC 2.0 format
No network exposure, pure local communication

3. Tool Handlers

Mỗi tool là một handler function
Validate input theo schema
Gọi VCI API thông qua adapter pattern
Format output và trả về Claude

4. Error Recovery

VCI API chậm → stream logs, không timeout
VCI API lỗi → graceful error response
Connection lost → auto-reconnect (Claude xử lý)

Adapter Pattern

vnstock-js dùng adapter pattern từ v1.0:

// VciAdapter implements StockDataAdapter interface
interface StockDataAdapter {
  getQuote(symbol: string): Promise<Quote>
  getHistory(symbol: string, options: HistoryOptions): Promise<HistoryData>
  // ... 9 more methods
}

// MCP Server gọi adapter
const mcp = new MCPServer({
  tools: [
    {
      name: "quote",
      handler: async (args) => {
        const data = await adapter.getQuote(args.symbol)
        return formatForClaude(data)
      }
    }
  ]
})

Điều này giữ cho core logic tách biệt từ transport layer.

Ví Dụ Tích Hợp

Claude Desktop: Portfolio Analysis

Prompt:

Tôi có danh mục: VCB 100 cổ phiếu, FPT 50 cổ phiếu, MBB 200 cổ phiếu.
Hiện tại nên giữ hay bán?

Claude sẽ:

Gọi quote cho VCB, FPT, MBB
Gọi indicators để lấy trend
Gọi aiContext để phân tích chi tiết
Tổng hợp lời khuyên

Claude Code: Automated Trading Signal

Script:

// Chạy hàng ngày via cron
const vnstock = require('vnstock-js');

async function analyzePortfolio() {
  const symbols = ['VCB', 'FPT', 'MBB'];
  
  for (const symbol of symbols) {
    const context = await vnstock.stock(symbol).aiContext();
    
    if (context.trend === 'bullish' && context.rsi < 70) {
      console.log(`BUY SIGNAL: ${symbol}`);
    } else if (context.trend === 'bearish' && context.rsi > 30) {
      console.log(`SELL SIGNAL: ${symbol}`);
    }
  }
}

analyzePortfolio();

Với MCP, bạn có thể để Claude Code tự gọi tools này thay vì viết code.

Cursor: Code-Aware Integration

Cursor hỗ trợ MCP trong composer, giúp bạn:

Viết code trading logic
Claude fetch dữ liệu real-time via MCP
Suggest improvements dựa trên dữ liệu thực

// Cursor composer suggestion:
// "Viết một hàm tìm arbitrage opportunity giữa VCB trên HOSE và HNX"

// Claude sẽ:
// 1. Gọi quote cho cả 2 sàn
// 2. Tính spread
// 3. Viết code optimal

Gỡ Lỗi & Khắc Phục Sự Cố

Kiểm Tra MCP Server Đang Chạy

Claude Desktop:

Mở DevTools: Cmd+Option+I (macOS) hoặc Ctrl+Shift+I (Windows)
Tìm logs có chứa "MCP server initialized"
Nếu không, xem lại claude_desktop_config.json

Claude Code:

Xem logs trong terminal
Tìm "MCP server started"

Lỗi Phổ Biến

Lỗi	Nguyên Nhân	Giải Pháp
`stdio not available`	vnstock-js không cài	`npm install vnstock-js`
`Tool not found`	Config sai	Reload Claude, xem syntax `claude_desktop_config.json`
`Timeout on quote`	VCI API chậm	Chờ, retry lại. VCI có rate limit ~100 req/min
`Invalid symbol`	Mã cổ phiếu sai	Dùng `listing` tool để confirm mã tồn tại
`Connection lost`	Network issue	Claude auto-reconnect sau 30s

Viewing MCP Logs

Claude Desktop:

# macOS
tail -f ~/Library/Logs/Claude/mcp_server.log

# Windows (PowerShell)
Get-Content $env:APPDATA\Claude\mcp_server.log -Tail 50 -Wait

Claude Code: Logs xuất ra terminal nơi bạn chạy Claude Code.

Performance Profiling

Nếu Claude chậm:

Check VCI API latency:

const start = Date.now();
const quote = await vnstock.stock('VCB').quote();
console.log(`VCI latency: ${Date.now() - start}ms`);

Check Claude logs: Tìm tool execution time
Common culprits:
- VCI API đang chậm (không phải lỗi của bạn)
- Quá nhiều tools gọi cùng lúc → batch requests
- Lookback quá lớn (1000+ phiên) → giảm xuống 100-200

Nâng Cao: Mở Rộng MCP

Thêm Custom Tools

Bạn có thể fork vnstock-js và thêm custom tools:

// bin/mcp-server.ts
import { MCPServer } from '@modelcontextprotocol/sdk'

const server = new MCPServer({
  tools: [
    // ... 11 standard tools ...
    
    // Custom tool
    {
      name: 'my-custom-tool',
      description: 'Bạn định nghĩa',
      inputSchema: {
        type: 'object',
        properties: {
          param1: { type: 'string' }
        }
      },
      handler: async (args) => {
        // Implement logic
        return { result: 'data' }
      }
    }
  ]
})

Chạy Multiple MCP Servers

Claude Desktop hỗ trợ multiple MCP servers:

{
  "mcpServers": {
    "vnstock-js": { ... },
    "weather-api": { ... },
    "news-feed": { ... }
  }
}

Claude sẽ có access đến tất cả tools.

Kết Hợp với MCP Servers Khác

Ví dụ: vnstock-js + news feed + weather

Prompt: "So sánh VCB và FPT. Có tin gì mới về ngành ngân hàng? Thời tiết Hà Nội?")

Claude sẽ:
1. quote, indicators (vnstock-js)
2. news search (news-feed MCP)
3. weather (weather MCP)
4. Tổng hợp câu trả lời

Kết Luận

MCP server của vnstock-js mở ra khả năng:

🎯 AI agents có access trực tiếp vào dữ liệu chứng khoán Việt
🔧 Zero setup complexity, một file config
🚀 Scale từ desktop → headless → production
🌐 Combine với MCP servers khác cho super-intelligence

Bây giờ Claude không chỉ biết chứng khoán, mà có thể phân tích, trade, và monitor portfolio của bạn. 🚀

PreviousAI Context

NextWatchlist

Nội Dung

Tại Sao MCP?Bắt Đầu Nhanh Yêu Cầu Claude Desktop Setup Claude Code Setup Cursor Setup Xác Minh Tools Tham Khảo Quote - Giá Cổ Phiếu Hiện Tại History - Lịch Sử Giá Company - Thông Tin Công Ty Dividends - Cổ Tức (v1.4.2+)Corporate Events - Sự Kiện Doanh Nghiệp (v1.4.2+)Trading - Dữ Liệu Giao Dịch Listing - Danh Sách Cổ Phiếu Indicators - Chỉ Báo Kỹ Thuật AI Context - Ngữ Cảnh AI Quick Quote - Giá Nhanh Top Movers - Top Tăng/Giảm Compare Symbols - So Sánh Cổ Phiếu Watchlist - Theo Dõi Danh Mục Kiến Trúc MCP Server Protocol Flow Thành Phần Chính Adapter Pattern Ví Dụ Tích Hợp Claude Desktop: Portfolio Analysis Claude Code: Automated Trading Signal Cursor: Code-Aware Integration Gỡ Lỗi & Khắc Phục Sự Cố Kiểm Tra MCP Server Đang Chạy Lỗi Phổ Biến Viewing MCP Logs Performance Profiling Nâng Cao: Mở Rộng MCP Thêm Custom Tools Chạy Multiple MCP Servers Kết Hợp với MCP Servers Khác Kết Luận

MCP Server

Model Context Protocol server cho vnstock-js — tích hợp Claude với dữ liệu chứng khoán Việt

Tại Sao MCP?

Trước đây, để Claude phân tích chứng khoán Việt, bạn cần:

Viết API wrapper riêng
Deploy server
Cấu hình API keys, authentication
Duy trì độc lập

Với MCP, Claude kết nối trực tiếp với vnstock-js thông qua stdio, không cần setup phức tạp. Một cấu hình, dùng ở mọi nơi.

Lợi ích:

🔌 Kết nối native với Claude Desktop, Claude Code, Cursor
🔐 Không expose public API, chạy local
⚡ Zero latency communication (stdio vs HTTP)
📱 Cùng config, dùng ở desktop, web, headless

Bắt Đầu Nhanh

Yêu Cầu

Node.js 16+
vnstock-js đã installed
```
npm install vnstock-js
```
Claude Desktop hoặc Claude Code (hoặc Cursor)

MCP SDK (@modelcontextprotocol/sdk) đã bao gồm trong vnstock-js — không cần cài thêm

Claude Desktop Setup

Tìm và mở file cấu hình Claude Desktop:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Thêm vnstock-js MCP server vào mcpServers:

{
  "mcpServers": {
    "vnstock-js": {
      "command": "npx",
      "args": ["-y", "vnstock-js", "mcp"]
    }
  }
}

Restart Claude Desktop. Lúc này Claude sẽ có quyền dùng 13 tools của vnstock-js.

Claude Code Setup

Trong Claude Code, dùng lệnh:

claude mcp add --scope user vnstock-js npx -y vnstock-js mcp

Verify:

claude mcp list
# Expected: vnstock-js: ... ✓ Connected

Hoặc cấu hình trong .claude/settings.local.json:

{
  "mcpServers": {
    "vnstock-js": {
      "command": "npx",
      "args": ["-y", "vnstock-js", "mcp"]
    }
  }
}

Cursor Setup

Tương tự Claude Code, thêm vào Cursor settings hoặc dùng MCP command line.

Xác Minh

Sau khi cấu hình, mở Claude và gõ:

Lấy giá hiện tại của VCB

Nếu Claude trả lời với dữ liệu VCB, MCP server đã kết nối thành công ✓

Tools Tham Khảo

Quote - Giá Cổ Phiếu Hiện Tại

Lấy giá khớp, thay đổi %, khối lượng, giá trần/sàn của một cổ phiếu.

Input:

symbol: string  // Mã cổ phiếu, ví dụ "VCB", "FPT"

Output:

{
  "symbol": "VCB",
  "matchingPrice": 105.2,
  "change": 1.2,
  "changePercent": 1.15,
  "volume": 15234500,
  "ceiling": 107.3,
  "floor": 103.1,
  "reference": 104.0
}

Ví dụ Claude prompt:

VCB giá bao nhiêu? Tăng hay giảm so với hôm qua?

History - Lịch Sử Giá

Lấy lịch sử giá (Open, High, Low, Close, Volume) trong khoảng thời gian.

Input:

symbol: string      // Mã cổ phiếu
from?: string       // YYYY-MM-DD, mặc định 30 ngày trước
to?: string         // YYYY-MM-DD, mặc định hôm nay
limit?: number      // Số phiên tối đa, mặc định 30

Output:

{
  "symbol": "VCB",
  "data": [
    {
      "date": "2026-05-23",
      "open": 104.0,
      "high": 105.5,
      "low": 103.8,
      "close": 105.2,
      "volume": 15234500
    }
  ]
}

Ví dụ Claude prompt:

Vẽ biểu đồ giá VCB 30 ngày qua. Xu hướng là tăng hay giảm?

Company - Thông Tin Công Ty

Lấy tên đầy đủ, ngành, sàn niêm yết của một cổ phiếu.

Input:

symbol: string  // Mã cổ phiếu

Output:

{
  "symbol": "VCB",
  "name": "Ngân Hàng Thương Mại Cổ Phần Vietcombank",
  "industry": "Ngân Hàng",
  "exchange": "HOSE"
}

Ví dụ Claude prompt:

VCB là công ty gì? Hoạt động ngành nào?

Dividends - Cổ Tức (v1.4.2+)

Lấy lịch sử & lịch chia cổ tức (tiền mặt + cổ phiếu): loại cổ tức, tỉ lệ/giá trị, ngày giao dịch không hưởng quyền (GDKHQ), ngày chốt danh sách.

Tool: get_dividends

Input:

symbol: string  // Mã cổ phiếu

Output: mảng CorporateEvent đã lọc cổ tức, mỗi phần tử gồm eventType, ratio, value, exRightDate, recordDate.

Ví dụ Claude prompt:

ACB chia cổ tức khi nào? Tỉ lệ bao nhiêu?

Corporate Events - Sự Kiện Doanh Nghiệp (v1.4.2+)

Lấy tất cả sự kiện doanh nghiệp: cổ tức, ĐHCĐ, phát hành thêm, niêm yết, giao dịch nội bộ.

Tool: get_corporate_events

Input:

symbol: string  // Mã cổ phiếu

Ví dụ Claude prompt:

HPG có sự kiện gì sắp tới?

Trading - Dữ Liệu Giao Dịch

Lấy thông tin giao dịch chi tiết: bid/ask, khối lượng mua/bán, giá trung bình.

Input:

symbol: string  // Mã cổ phiếu

Output:

{
  "symbol": "VCB",
  "buyPrice": 105.1,
  "buyVolume": 524000,
  "sellPrice": 105.2,
  "sellVolume": 478000,
  "totalVolume": 15234500,
  "averagePrice": 104.98
}

Ví dụ Claude prompt:

Giá bid/ask của FPT bây giờ là bao nhiêu?

Listing - Danh Sách Cổ Phiếu

Lấy danh sách tất cả cổ phiếu trên một sàn (HOSE, HNX, UPCOM).

Input:

exchange?: string  // "HOSE", "HNX", "UPCOM" (mặc định: tất cả)
limit?: number     // Số mã tối đa, mặc định 100

Output:

{
  "symbols": ["VCB", "FPT", "MBB", ...],
  "total": 403
}

Ví dụ Claude prompt:

Có bao nhiêu cổ phiếu trên HOSE?

Indicators - Chỉ Báo Kỹ Thuật

Tính toán MACD, Bollinger Bands, ATR cho một cổ phiếu.

Input:

symbol: string          // Mã cổ phiếu
indicator: string       // "macd" | "bollinger" | "atr"
period?: number         // Chu kỳ, mặc định 20/12
lookback?: number       // Số phiên lịch sử, mặc định 100

Output (MACD):

{
  "indicator": "macd",
  "symbol": "VCB",
  "data": [
    {
      "date": "2026-05-23",
      "macd": 0.45,
      "signal": 0.38,
      "histogram": 0.07
    }
  ]
}

Ví dụ Claude prompt:

Tính MACD cho VCB. Tín hiệu bullish hay bearish?

AI Context - Ngữ Cảnh AI

Lấy phân tích kỹ thuật tích hợp: trend, indicators, support/resistance, volume signal.

Input:

symbol: string      // Mã cổ phiếu
lookback?: number   // Số phiên, mặc định 200

Output:

{
  "symbol": "VCB",
  "trend": "bullish",
  "indicators": {
    "rsi": 65.2,
    "macd": { "signal": "bullish", "histogram": 0.07 },
    "sma20": 104.5,
    "sma50": 103.2,
    "sma200": 102.1
  },
  "support": 104.0,
  "resistance": 106.5,
  "volumeSignal": "strong",
  "priceChange": { "1d": 1.15, "7d": 2.5, "30d": 5.2 }
}

Ví dụ Claude prompt:

Phân tích kỹ thuật VCB. Nên mua hay bán?

Quick Quote - Giá Nhanh

Lấy giá của nhiều cổ phiếu cùng lúc (shorthand cho multiple quote calls).

Input:

symbols: string[]  // Mảng mã cổ phiếu, ví dụ ["VCB", "FPT", "MBB"]

Output:

{
  "data": [
    { "symbol": "VCB", "price": 105.2, "change": 1.15 },
    { "symbol": "FPT", "price": 89.5, "change": -0.5 },
    { "symbol": "MBB", "price": 26.3, "change": 2.1 }
  ]
}

Ví dụ Claude prompt:

So sánh giá VCB, FPT, MBB

Top Movers - Top Tăng/Giảm

Lấy top 10 cổ phiếu tăng mạnh và giảm mạnh hôm nay.

Input:

limit?: number  // Số mã mỗi bên, mặc định 10

Output:

{
  "gainers": [
    { "symbol": "AAA", "price": 10.5, "change": 3.2 },
    { "symbol": "BBB", "price": 20.1, "change": 2.8 }
  ],
  "losers": [
    { "symbol": "CCC", "price": 15.2, "change": -2.5 },
    { "symbol": "DDD", "price": 8.9, "change": -1.9 }
  ]
}

Ví dụ Claude prompt:

Hôm nay cổ phiếu nào tăng mạnh nhất?

Compare Symbols - So Sánh Cổ Phiếu

So sánh side-by-side giá, thay đổi %, RSI, volume signal của nhiều cổ phiếu.

Input:

symbols: string[]  // Mảng mã cổ phiếu

Output:

{
  "comparison": [
    {
      "symbol": "VCB",
      "price": 105.2,
      "change%": 1.15,
      "rsi": 65.2,
      "volumeSignal": "strong"
    },
    {
      "symbol": "MBB",
      "price": 26.3,
      "change%": 2.1,
      "rsi": 58.5,
      "volumeSignal": "normal"
    }
  ]
}

Ví dụ Claude prompt:

So sánh VCB, MBB, TCB. Cái nào tốt nhất để đầu tư?

Watchlist - Theo Dõi Danh Mục

CRUD (Create, Read, Update, Delete) cho danh mục theo dõi. Dữ liệu lưu tại ~/.vnstock-js/watchlist.json.

Input (Add):

action: "add"
name: string       // Tên danh mục, ví dụ "Tech Stocks"
symbol: string     // Mã cổ phiếu

Input (List):

action: "list"

Output:

{
  "watchlists": [
    {
      "name": "Tech Stocks",
      "symbols": ["FPT", "VNM", "DIG"],
      "createdAt": "2026-05-23T10:30:00Z"
    }
  ]
}

Ví dụ Claude prompt:

Thêm VCB vào danh mục "Ngân Hàng" của tôi
Hiển thị danh mục theo dõi của tôi

Kiến Trúc MCP Server

Protocol Flow

Claude              MCP Transport       vnstock-js Server       VCI API
   |                     |                    |                    |
   |--- Initialize ----->|                    |                    |
   |                     |--- Start Process -->|                    |
   |                     |                    |-- Connection OK ---|
   |                     |<--- Ready ---------|                    |
   |                     |                    |                    |
   |--- List Tools ----->|                    |                    |
   |                     |-- list_tools ----->|                    |
   |<----- Tools List ----|<-- Tool Schema ---|                    |
   |                     |                    |                    |
   |--- Call Tool ------>|                    |                    |
   | (quote, VCB)        |--- call_tool ----->|                    |
   |                     |                    |--- Fetch Data ---->|
   |                     |                    |<---- Response -----|
   |                     |<---- Result -------|                    |
   |<---- Response ------|                    |                    |

Thành Phần Chính

1. Server Initialization

vnstock-js khởi tạo MCP Server instance với stdio transport
Đăng ký 13 tools và schema của chúng

2. Transport Layer

stdio: stdin (request từ Claude) ↔ stdout (response)
JSON-RPC 2.0 format
No network exposure, pure local communication

3. Tool Handlers

Mỗi tool là một handler function
Validate input theo schema
Gọi VCI API thông qua adapter pattern
Format output và trả về Claude

4. Error Recovery

VCI API chậm → stream logs, không timeout
VCI API lỗi → graceful error response
Connection lost → auto-reconnect (Claude xử lý)

Adapter Pattern

vnstock-js dùng adapter pattern từ v1.0:

// VciAdapter implements StockDataAdapter interface
interface StockDataAdapter {
  getQuote(symbol: string): Promise<Quote>
  getHistory(symbol: string, options: HistoryOptions): Promise<HistoryData>
  // ... 9 more methods
}

// MCP Server gọi adapter
const mcp = new MCPServer({
  tools: [
    {
      name: "quote",
      handler: async (args) => {
        const data = await adapter.getQuote(args.symbol)
        return formatForClaude(data)
      }
    }
  ]
})

Điều này giữ cho core logic tách biệt từ transport layer.

Ví Dụ Tích Hợp

Claude Desktop: Portfolio Analysis

Prompt:

Tôi có danh mục: VCB 100 cổ phiếu, FPT 50 cổ phiếu, MBB 200 cổ phiếu.
Hiện tại nên giữ hay bán?

Claude sẽ:

Gọi quote cho VCB, FPT, MBB
Gọi indicators để lấy trend
Gọi aiContext để phân tích chi tiết
Tổng hợp lời khuyên

Claude Code: Automated Trading Signal

Script:

// Chạy hàng ngày via cron
const vnstock = require('vnstock-js');

async function analyzePortfolio() {
  const symbols = ['VCB', 'FPT', 'MBB'];
  
  for (const symbol of symbols) {
    const context = await vnstock.stock(symbol).aiContext();
    
    if (context.trend === 'bullish' && context.rsi < 70) {
      console.log(`BUY SIGNAL: ${symbol}`);
    } else if (context.trend === 'bearish' && context.rsi > 30) {
      console.log(`SELL SIGNAL: ${symbol}`);
    }
  }
}

analyzePortfolio();

Với MCP, bạn có thể để Claude Code tự gọi tools này thay vì viết code.

Cursor: Code-Aware Integration

Cursor hỗ trợ MCP trong composer, giúp bạn:

Viết code trading logic
Claude fetch dữ liệu real-time via MCP
Suggest improvements dựa trên dữ liệu thực

// Cursor composer suggestion:
// "Viết một hàm tìm arbitrage opportunity giữa VCB trên HOSE và HNX"

// Claude sẽ:
// 1. Gọi quote cho cả 2 sàn
// 2. Tính spread
// 3. Viết code optimal

Gỡ Lỗi & Khắc Phục Sự Cố

Kiểm Tra MCP Server Đang Chạy

Claude Desktop:

Mở DevTools: Cmd+Option+I (macOS) hoặc Ctrl+Shift+I (Windows)
Tìm logs có chứa "MCP server initialized"
Nếu không, xem lại claude_desktop_config.json

Claude Code:

Xem logs trong terminal
Tìm "MCP server started"

Lỗi Phổ Biến

Lỗi	Nguyên Nhân	Giải Pháp
`stdio not available`	vnstock-js không cài	`npm install vnstock-js`
`Tool not found`	Config sai	Reload Claude, xem syntax `claude_desktop_config.json`
`Timeout on quote`	VCI API chậm	Chờ, retry lại. VCI có rate limit ~100 req/min
`Invalid symbol`	Mã cổ phiếu sai	Dùng `listing` tool để confirm mã tồn tại
`Connection lost`	Network issue	Claude auto-reconnect sau 30s

Viewing MCP Logs

Claude Desktop:

# macOS
tail -f ~/Library/Logs/Claude/mcp_server.log

# Windows (PowerShell)
Get-Content $env:APPDATA\Claude\mcp_server.log -Tail 50 -Wait

Claude Code: Logs xuất ra terminal nơi bạn chạy Claude Code.

Performance Profiling

Nếu Claude chậm:

Check VCI API latency:

const start = Date.now();
const quote = await vnstock.stock('VCB').quote();
console.log(`VCI latency: ${Date.now() - start}ms`);

Check Claude logs: Tìm tool execution time
Common culprits:
- VCI API đang chậm (không phải lỗi của bạn)
- Quá nhiều tools gọi cùng lúc → batch requests
- Lookback quá lớn (1000+ phiên) → giảm xuống 100-200

Nâng Cao: Mở Rộng MCP

Thêm Custom Tools

Bạn có thể fork vnstock-js và thêm custom tools:

// bin/mcp-server.ts
import { MCPServer } from '@modelcontextprotocol/sdk'

const server = new MCPServer({
  tools: [
    // ... 11 standard tools ...
    
    // Custom tool
    {
      name: 'my-custom-tool',
      description: 'Bạn định nghĩa',
      inputSchema: {
        type: 'object',
        properties: {
          param1: { type: 'string' }
        }
      },
      handler: async (args) => {
        // Implement logic
        return { result: 'data' }
      }
    }
  ]
})

Chạy Multiple MCP Servers

Claude Desktop hỗ trợ multiple MCP servers:

{
  "mcpServers": {
    "vnstock-js": { ... },
    "weather-api": { ... },
    "news-feed": { ... }
  }
}

Claude sẽ có access đến tất cả tools.

Kết Hợp với MCP Servers Khác

Ví dụ: vnstock-js + news feed + weather

Prompt: "So sánh VCB và FPT. Có tin gì mới về ngành ngân hàng? Thời tiết Hà Nội?")

Claude sẽ:
1. quote, indicators (vnstock-js)
2. news search (news-feed MCP)
3. weather (weather MCP)
4. Tổng hợp câu trả lời

Kết Luận

MCP server của vnstock-js mở ra khả năng:

🎯 AI agents có access trực tiếp vào dữ liệu chứng khoán Việt
🔧 Zero setup complexity, một file config
🚀 Scale từ desktop → headless → production
🌐 Combine với MCP servers khác cho super-intelligence

Bây giờ Claude không chỉ biết chứng khoán, mà có thể phân tích, trade, và monitor portfolio của bạn. 🚀

PreviousAI Context

NextWatchlist

Bắt Đầu

Tính Năng

Dữ Liệu

Bắt Đầu

Tính Năng

Dữ Liệu

MCP Server

Tại Sao MCP?

Bắt Đầu Nhanh

Yêu Cầu

Claude Desktop Setup

Claude Code Setup

Cursor Setup

Xác Minh

Tools Tham Khảo

Quote - Giá Cổ Phiếu Hiện Tại

History - Lịch Sử Giá

Company - Thông Tin Công Ty

Dividends - Cổ Tức (v1.4.2+)

Corporate Events - Sự Kiện Doanh Nghiệp (v1.4.2+)

Trading - Dữ Liệu Giao Dịch

Listing - Danh Sách Cổ Phiếu

Indicators - Chỉ Báo Kỹ Thuật

AI Context - Ngữ Cảnh AI

Quick Quote - Giá Nhanh

Top Movers - Top Tăng/Giảm

Compare Symbols - So Sánh Cổ Phiếu

Watchlist - Theo Dõi Danh Mục

Kiến Trúc MCP Server

Protocol Flow

Thành Phần Chính

Adapter Pattern

Ví Dụ Tích Hợp

Claude Desktop: Portfolio Analysis

Claude Code: Automated Trading Signal

Cursor: Code-Aware Integration

Gỡ Lỗi & Khắc Phục Sự Cố

Kiểm Tra MCP Server Đang Chạy

Lỗi Phổ Biến

Viewing MCP Logs

Performance Profiling

Nâng Cao: Mở Rộng MCP

Thêm Custom Tools

Chạy Multiple MCP Servers

Kết Hợp với MCP Servers Khác

Kết Luận

Nội Dung

MCP Server

Tại Sao MCP?

Bắt Đầu Nhanh

Yêu Cầu

Claude Desktop Setup

Claude Code Setup

Cursor Setup

Xác Minh

Tools Tham Khảo

Quote - Giá Cổ Phiếu Hiện Tại

History - Lịch Sử Giá

Company - Thông Tin Công Ty

Dividends - Cổ Tức (v1.4.2+)

Corporate Events - Sự Kiện Doanh Nghiệp (v1.4.2+)

Trading - Dữ Liệu Giao Dịch

Listing - Danh Sách Cổ Phiếu

Indicators - Chỉ Báo Kỹ Thuật

AI Context - Ngữ Cảnh AI

Quick Quote - Giá Nhanh

Top Movers - Top Tăng/Giảm

Compare Symbols - So Sánh Cổ Phiếu

Watchlist - Theo Dõi Danh Mục

Kiến Trúc MCP Server

Protocol Flow

Thành Phần Chính

Adapter Pattern

Ví Dụ Tích Hợp

Claude Desktop: Portfolio Analysis

Claude Code: Automated Trading Signal

Cursor: Code-Aware Integration

Gỡ Lỗi & Khắc Phục Sự Cố

Kiểm Tra MCP Server Đang Chạy

Lỗi Phổ Biến