Skip to main content
Glama
VNStock Agent

VNStock Agent

by anhnd2102

VNStock Agent

MCP server and CLI for Vietnamese stock market data. Integrates vnstock (hỗ trợ tác giả gốc thinh-vu) with AI tools via Model Context Protocol (MCP).

Features

  • 21 MCP tools for AI assistants (Claude, GPT, etc.)

  • 22 CLI commands for terminal use

  • 3 MCP transports: stdio, SSE, Streamable HTTP

  • Vietnamese stocks, forex, crypto, world indices, mutual funds

  • Historical prices, financials, company info, trading data

Related MCP server: vnstock-mcp

Quick Start

Install

pip install vnstock-agent

Or from source:

git clone https://github.com/anhnd2102/vnstock-mcp.git
cd vnstock-mcp
pip install -e .

Set API Key

export VNSTOCK_API_KEY=your_api_key_here

Get a free API key at vnstocks.com/login.

CLI Usage

# Stock history
vnstock-agent history VNM --start 2025-01-01 --end 2025-03-31

# Company overview
vnstock-agent overview FPT

# Financial statements
vnstock-agent balance-sheet VCB --period quarter
vnstock-agent income VCB --period annual
vnstock-agent cashflow VCB
vnstock-agent ratio VCB

# Market data
vnstock-agent symbols                    # All listed symbols
vnstock-agent group --group VN30         # VN30 stocks
vnstock-agent board "VNM,FPT,ACB,VCB"   # Price board
vnstock-agent industries                 # ICB industries

# Company details
vnstock-agent shareholders FPT
vnstock-agent officers FPT
vnstock-agent news FPT
vnstock-agent events FPT

# Intraday & depth
vnstock-agent intraday VNM --page-size 200

# Global markets
vnstock-agent fx EURUSD --start 2025-01-01
vnstock-agent crypto BTC --start 2025-01-01
vnstock-agent index DJI --start 2025-01-01

# Mutual funds
vnstock-agent funds

# JSON output
vnstock-agent --format json history VNM

MCP Server

stdio (for Claude Desktop, Cursor, etc.)

Add to your MCP client config:

{
  "mcpServers": {
    "vnstock": {
      "command": "vnstock-mcp",
      "env": {
        "VNSTOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

SSE Transport

VNSTOCK_MCP_TRANSPORT=sse VNSTOCK_MCP_PORT=8000 vnstock-mcp

Streamable HTTP Transport

VNSTOCK_MCP_TRANSPORT=http VNSTOCK_MCP_PORT=8000 vnstock-mcp

Or via CLI:

vnstock-agent serve --transport sse --port 8000
vnstock-agent serve --transport http --port 8000

MCP Tools

Tool

Description

stock_history

Historical OHLCV price data

stock_intraday

Today's intraday trading data

stock_price_depth

Order book / bid-ask data

company_overview

Company overview info

company_shareholders

Major shareholders

company_officers

Management team

company_news

Company news

company_events

Dividends, AGM, etc.

financial_balance_sheet

Balance sheet

financial_income_statement

Income statement

financial_cash_flow

Cash flow statement

financial_ratio

P/E, P/B, ROE, ROA, etc.

listing_all_symbols

All listed symbols

listing_symbols_by_group

VN30, HNX30, etc.

listing_symbols_by_exchange

By exchange (HOSE, HNX, UPCOM)

listing_industries

ICB industry classification

trading_price_board

Real-time price board

fx_history

Forex historical data

crypto_history

Cryptocurrency data

world_index_history

World market indices

fund_listing

Mutual fund listing

Environment Variables

Variable

Default

Description

VNSTOCK_API_KEY

(none)

VNStock API key

VNSTOCK_SOURCE

VCI

Default data source (VCI, KBS)

VNSTOCK_MCP_TRANSPORT

stdio

MCP transport (stdio, sse, http)

VNSTOCK_MCP_HOST

0.0.0.0

Server host

VNSTOCK_MCP_PORT

8000

Server port

Development

git clone https://github.com/anhnd2102/vnstock-mcp.git
cd vnstock-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

License

MIT

Available Tools

21 tools
company_eventsC

Get company events (dividends, AGM, earnings, etc).

Inputs: symbol (required), source. Returns: result

company_newsB

Get latest news about a company.

Inputs: symbol (required), source. Returns: result

company_officersC

Get company officers / management team.

Inputs: symbol (required), source. Returns: result

company_overviewC

Get company overview information (industry, market cap, description, etc).

Inputs: symbol (required), source. Returns: result

company_shareholdersC

Get major shareholders of a company.

Inputs: symbol (required), source. Returns: result

crypto_historyB

Get cryptocurrency historical price data.

Inputs: end, start, symbol, interval. Returns: result

financial_balance_sheetC

Get balance sheet data for a company.

Inputs: symbol (required), period, source. Returns: result

financial_cash_flowC

Get cash flow statement for a company.

Inputs: symbol (required), period, source. Returns: result

financial_income_statementC

Get income statement data for a company.

Inputs: symbol (required), period, source. Returns: result

financial_ratioB

Get financial ratios (P/E, P/B, ROE, ROA, etc) for a company.

Inputs: symbol (required), period, source. Returns: result

fund_listingB

Get list of open-ended mutual funds available in Vietnam.

Inputs: no named parameters. Returns: result

fx_historyC

Get forex (currency pair) historical price data.

Inputs: end, start, symbol, interval. Returns: result

listing_all_symbolsA

Get all listed stock symbols on Vietnamese exchanges (HOSE, HNX, UPCOM).

Inputs: source. Returns: result

listing_industriesC

Get ICB industry classification for Vietnamese stocks.

Inputs: source. Returns: result

listing_symbols_by_exchangeA

Get stock symbols grouped by exchange (HOSE, HNX, UPCOM).

Inputs: source. Returns: result

listing_symbols_by_groupC

Get stock symbols in a market group.

Inputs: group, source. Returns: result

stock_historyB

Get historical OHLCV price data for a Vietnamese stock.

Inputs: symbol (required), end, start, source, +1 more. Returns: result

stock_intradayB

Get intraday (today's) trading data for a stock.

Inputs: symbol (required), source, page_size. Returns: result

stock_price_depthB

Get order book / price depth (bid/ask levels) for a stock.

Inputs: symbol (required), source. Returns: result

trading_price_boardB

Get real-time price board for multiple stocks.

Inputs: symbols (required), source. Returns: result

world_index_historyC

Get world market index historical data.

Inputs: end, start, symbol, interval. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a distinct resource (stock, company, financial statement, listing, market data, fund) with a specific action. The prefixes stock_, company_, financial_, listing_, trading_, fx_, crypto_, world_index_, and fund_ cleanly separate domains with no overlapping purposes.

    Naming Consistency4/5

    The naming follows a consistent category_prefix + noun pattern (stock_history, company_overview, financial_ratio, listing_all_symbols). The intraday vs history distinction is slightly odd (temporal vs derivative terms) but broadly consistent. Minor deviations like trading_price_board vs the rest don't undermine readability.

    Tool Count5/5

    21 tools is on the upper boundary but the scope is genuinely broad: Vietnam stock market data (core), company fundamentals, financial statements, listing info, plus supplementary FX/crypto/world index/mutual fund data. Each tool maps to a distinct data category a Vietnam equity research agent would need.

    Completeness4/5

    The surface covers the full data stack for Vietnam equity research: market data (history, intraday, depth, price board), fundamentals (financial statements, ratios), company info (overview, shareholders, officers, news, events), and listings. Minor gaps include missing order/trade execution tools and no company_announcements separate from news, but these are not core to a data-provider role.

    Related MCP Connectors

    Related MCP Servers