VNStock Agent MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VNStock Agent MCP Server What's the stock history for VNM this year?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
VNStock Agent
MCP server and CLI for Vietnamese stock market data. Integrates vnstock 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: SSI Stock Data MCP Server
Quick Start
Install
pip install vnstock-agentOr from source:
git clone https://github.com/mrgoonie/vnstock-agent.git
cd vnstock-agent
pip install -e .Set API Key
export VNSTOCK_API_KEY=your_api_key_hereGet 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 VNMMCP 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-mcpStreamable HTTP Transport
VNSTOCK_MCP_TRANSPORT=http VNSTOCK_MCP_PORT=8000 vnstock-mcpOr via CLI:
vnstock-agent serve --transport sse --port 8000
vnstock-agent serve --transport http --port 8000MCP Tools
Tool | Description |
| Historical OHLCV price data |
| Today's intraday trading data |
| Order book / bid-ask data |
| Company overview info |
| Major shareholders |
| Management team |
| Company news |
| Dividends, AGM, etc. |
| Balance sheet |
| Income statement |
| Cash flow statement |
| P/E, P/B, ROE, ROA, etc. |
| All listed symbols |
| VN30, HNX30, etc. |
| By exchange (HOSE, HNX, UPCOM) |
| ICB industry classification |
| Real-time price board |
| Forex historical data |
| Cryptocurrency data |
| World market indices |
| Mutual fund listing |
Environment Variables
Variable | Default | Description |
| (none) | VNStock API key |
|
| Default data source (VCI, KBS) |
|
| MCP transport (stdio, sse, http) |
|
| Server host |
|
| Server port |
Development
git clone https://github.com/mrgoonie/vnstock-agent.git
cd vnstock-agent
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Run tests
pytest
# Lint
ruff check src/License
MIT
Available Tools
21 toolscompany_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
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
Scored across 21 tools
Most tools are clearly separated by domain (company, stock, financial, listing, etc.), but the three listing tools (all_symbols, by_group, by_exchange) overlap heavily and could cause misselection. Stock history, intraday, and price board also have related purposes, though descriptions help distinguish them.
All names use lowercase snake_case with a domain prefix, which is predictable. The pattern is not strictly verb_noun (some are noun_noun like 'company_events', some gerund-based like 'listing_all_symbols'), but within each domain the style is uniform and readable.
21 tools is slightly above the typical comfortable range, but the server covers a broad domain (Vietnamese equities, forex, crypto, world indices, funds) and each tool addresses a distinct data need. The count feels justified rather than bloated.
The toolset covers the core lifecycle of market data: company fundamentals, financial statements, price history, intraday data, depth, listings, and news. It also extends to other asset classes. Minor gaps like missing specific company dividend details (subsumed by events) or quote snapshot endpoint are workarounds.
Related MCP Connectors
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
MCP server for Financial Modeling Prep API with 250+ financial data tools
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Research-only MCP server: your AI as a quant research desk. 90 tools, no trades, no brokers.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.112,324MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables AI assistants to query Vietnam stock intraday data from SSI FastConnect API, providing access to stock codes, detailed information, index data, and OHLC information through natural language queries.17Apache 2.0
- AlicenseNot gradedqualityDmaintenanceUnofficial MCP server providing Vietnamese stock market financial data, enabling natural language interaction with Claude Desktop.29 PyPIMIT
- AlicenseBqualityCmaintenanceMCP server providing Vietnamese stock market data including historical prices, financial statements, company info, trading data, forex, crypto, world indices, and mutual funds through 21 MCP tools and 22 CLI commands with support for stdio, SSE, and Streamable HTTP transports.21MIT