VNStock 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 MCP Server Get the latest stock price for VNM (Vinamilk)."
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 MCP Server (Unofficial)
An unofficial MCP (Model Context Protocol) server that provides tools to access Vietnam stock market data. This is a wrapper around the excellent vnstock library by @thinh-vu.
Note: This is an independent project and is not officially affiliated with the vnstock library or its maintainers.
About vnstock
This MCP server is built on top of the vnstock library - a powerful Python toolkit for Vietnamese stock market analysis created by Thinh Vu. vnstock provides comprehensive access to Vietnam stock market data including:
Real-time and historical stock prices
Company financial statements
Market data and trading statistics
Mutual fund information
Gold prices and exchange rates
For more information about the underlying library, visit: https://github.com/thinh-vu/vnstock
Related MCP server: VNStock MCP Server
Features
This MCP server exposes vnstock's capabilities through MCP tools, allowing AI assistants and other MCP clients to:
Access company information and financial data
Retrieve stock quotes and historical prices
Get trading statistics and market data
Query mutual fund information
Access gold prices and exchange rates
Retrieve financial statements (income, balance sheet, cash flow)
Installation
Install from PyPI (Recommended)
pip install vnstock-mcp-serverInstall from source
git clone https://github.com/maobui/vnstock-mcp-server.git
cd vnstock-mcp-server
uv syncPrerequisites
Python 3.12+
uv (install with
pip install uvor seehttps://docs.astral.sh/uv/)
Quick Start
Run the MCP server
Default mode (stdio)
# If installed from PyPI
vnstock-mcp-server
# If installed from source with uv
uv run python -m vnstock_mcp.serverWith transport options
# Use stdio transport (default)
vnstock-mcp-server --transport stdio
# Use Server-Sent Events (SSE) transport for web applications
vnstock-mcp-server --transport sse
# Use SSE with custom endpoint path
vnstock-mcp-server --transport sse --path /mcp
# Use HTTP streaming transport
vnstock-mcp-server --transport streamable-http
# Show help with all available options
vnstock-mcp-server --helpThe server uses FastMCP and supports multiple transport protocols:
stdio: Standard input/output (default, for MCP clients like Claude Desktop)
sse: Server-Sent Events (for web applications)
streamable-http: HTTP streaming (for HTTP-based integrations)
Transport Modes
The VNStock MCP Server supports three different transport protocols to accommodate various use cases:
stdio (Default)
Use case: Standard MCP clients like Claude Desktop, Cursor, Cline
Protocol: Communication via standard input/output streams
Usage:
vnstock-mcp-serverorvnstock-mcp-server --transport stdioBest for: Desktop applications and traditional MCP integrations
SSE (Server-Sent Events)
Use case: Web applications that need real-time data streaming
Protocol: HTTP-based server-sent events
Usage:
vnstock-mcp-server --transport sse [--path /mcp] [--host 0.0.0.0] [--port 8000]Server runs on:
http://127.0.0.1:8000(default)Best for: Web dashboards, browser-based applications
streamable-http
Use case: HTTP-based integrations and API services
Protocol: HTTP streaming with JSON-RPC over HTTP
Usage:
vnstock-mcp-server --transport streamable-http [--path /mcp] [--host 0.0.0.0] [--port 8000]Server runs on:
http://127.0.0.1:8000(default)Best for: REST API integrations, microservices architecture
Command Line Options
vnstock-mcp-server [OPTIONS]
Options:
-t, --transport {stdio,sse,streamable-http}
Transport protocol to use (default: stdio)
--path PATH Endpoint path for HTTP transports (optional, e.g. /mcp)
--host HOST Host address to bind to (default: 0.0.0.0)
-p, --port PORT Port to run the server on (default: 8000)
-v, --version Show version information
-h, --help Show help messageMCP client integration
Cursor / Cline example
Add a server entry in your MCP configuration:
Default stdio transport
{
"mcpServers": {
"vnstock": {
"command": "uvx",
"args": [
"vnstock-mcp-server"
]
}
}
}With specific transport options
{
"mcpServers": {
"vnstock-sse": {
"command": "uvx",
"args": [
"vnstock-mcp-server",
"--transport",
"sse",
"--path",
"/mcp",
"--port",
"8000"
]
},
"vnstock-http": {
"command": "uvx",
"args": [
"vnstock-mcp-server",
"--transport",
"streamable-http"
]
}
}
}If installed from source:
{
"mcpServers": {
"vnstock": {
"command": "uv",
"args": ["run", "python", "-m", "vnstock_mcp.server"],
"env": {}
},
"vnstock-sse": {
"command": "uv",
"args": ["run", "python", "-m", "vnstock_mcp.server", "--transport", "sse"],
"env": {}
}
}
}Claude Desktop example
In MCP server settings:
Command:
vnstock-mcp-serverArgs: (leave empty for stdio, or add transport options like
--transport sse)
Available Tools
The MCP server provides the following categories of tools:
Company Information
Company overview, news, events
Shareholders and officers information
Subsidiaries and insider deals
Trading statistics and ratios
Financial Data
Income statements, balance sheets, cash flows
Financial ratios and raw reports
Historical financial data (quarterly/yearly)
Market Data
Real-time quotes and historical prices
Intraday trading data and price depth
Market price boards for multiple symbols
Fund Information
Fund listings and search
NAV reports and holdings
Industry and asset allocation
Miscellaneous
Gold prices (SJC, BTMC)
Exchange rates
Symbol listings by industry/group
Development
Install with uv (for development)
# From the project root
uv sync
# Include dev dependencies (for tests and coverage)
uv sync --group devTesting with uv
# Run all tests
uv run pytest
# Run a specific test file
uv run pytest test/test_company_tools.py
# Run with coverage (HTML)
uv run pytest --cov=src/vnstock_mcp --cov-report=html
# Open report:
# ./htmlcov/index.htmlBuilding and Publishing
Build locally
# Using the build script
./scripts/build.sh
# Or manually
python -m buildCreate a release
# Update version in pyproject.toml first, then:
./scripts/release.shThis will:
Run tests
Create and push a git tag
Trigger GitHub Actions to build and publish to PyPI
Credits
This project is a wrapper around the vnstock library created by @thinh-vu. All stock market data access functionality is provided by vnstock.
Please consider:
β Starring the original vnstock repository
π Reading the vnstock documentation
π Supporting the vnstock project if you find it valuable
Disclaimer
This is an unofficial wrapper and is not affiliated with the vnstock library or its maintainers. For issues related to the underlying stock market data or vnstock functionality, please refer to the vnstock repository.
Troubleshooting
Installation Issues
Module not found with
uv run:Ensure
uv synccompleted successfully in the project root.Verify Python version:
python --versionanduv python list.
Command
vnstock-mcp-servernot found:Ensure the package is installed:
pip list | grep vnstock-mcp-serverTry reinstalling:
pip install --upgrade vnstock-mcp-server
Connection Issues
MCP client cannot connect (stdio mode):
Confirm the client configuration matches the installation method
Check client logs for detailed errors.
Ensure no extra arguments are passed for stdio transport
Cannot access SSE/HTTP endpoints:
Verify the server is running: check for "Uvicorn running on http://127.0.0.1:8000"
Check if port 8000 is available:
netstat -an | grep 8000Try accessing
http://127.0.0.1:8000in browser for SSE mode
Transport Mode Issues
SSE transport not working:
Ensure path is correctly specified if needed
Check server logs for startup errors
Verify web client can connect to the SSE endpoint
Wrong transport mode selected:
Use
--helpto see available transport optionsstdio: for desktop MCP clients (Claude Desktop, Cursor)
sse: for web applications
streamable-http: for HTTP API integrations
Getting Help
Check server version:
vnstock-mcp-server --versionView all options:
vnstock-mcp-server --helpTest server startup: Run with
--transport stdiofirst to verify basic functionality
License
MIT License - see LICENSE file for details.
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run tests:
uv run pytestSubmit a pull request
Changelog
v1.0.4 (Latest)
NEW: Added Technical Analysis (TA) Trend Indicators - 15+ trend indicators including ADX, Aroon, Ichimoku, Parabolic SAR, SuperTrend, PSAR, and more
NEW: Added Technical Analysis (TA) Volume Indicators - 15+ volume indicators including OBV, AD, CMF, MFI, VWMA, and more
NEW: Modular TA architecture with separate modules for Momentum, Trend, and Volume indicators
NEW: Core utility functions in
ta_core.pyfor indicator metadata extraction and result mergingIMPROVED: Comprehensive docstrings with accurate
Output columnsdocumentation for all indicatorsIMPROVED: Unified indicator registry combining all indicator categories
IMPROVED: Better test coverage with separate test files for each indicator category
FIXED: Fixed test failures in quote tools related to OHLCV data requirements
v1.0.3
NEW: Added Technical Analysis (TA) Momentum Indicators support via
pandas-talibraryNEW: 40+ momentum indicators including RSI, MACD, Stochastic, CCI, Williams %R, ADX, and more
NEW:
add_indicator()function for dynamic indicator addition with string parsingNEW:
get_available_indicators()andget_indicator_info()for indicator discoveryNEW: Support for custom indicator parameters via string or kwargs
IMPROVED: Enhanced quote tools with integrated TA momentum analysis
v1.0.2
NEW: Added TOON (python-toon) support for enhanced functionality
IMPROVED: Separated MCP tools into individual files for better code organization
FIXED: SSE transport connection issues
v1.0.1
NEW: Added support for multiple transport modes (stdio, sse, streamable-http)
NEW: Command line arguments for transport selection (
--transport,--path,--host,--port)NEW: SSE (Server-Sent Events) transport for web applications
NEW: HTTP streaming transport for API integrations
IMPROVED: Enhanced CLI with help messages and validation
IMPROVED: Better error handling and user feedback
IMPROVED: Comprehensive documentation for all transport modes
v1.0.0
Initial release
Full Vietnam stock market data access via MCP
Support for company data, financial statements, quotes, and more
Wrapper around vnstock v3.2.6+
Available Tools
36 toolsget_all_symbol_groupsB
Get all symbol groups from stock market Args: output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: output_format.
get_all_symbolsB
Get all symbols from stock market Args: output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame or json
Inputs: output_format.
get_all_symbols_by_groupC
Get all symbols from stock market Args: group: str (group name to get symbols) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: group (required), output_format.
get_all_symbols_by_industryA
Get all symbols from stock market Args: industry: str = None (if None, return all symbols) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame or json
Inputs: industry, output_format.
get_all_symbols_detailedB
Get all symbols detailed from stock market Args: output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: output_format.
get_balance_sheetsC
Get balance sheets of a company from stock market Args: symbol: str (symbol of the company to get balance sheets) period: Literal['quarter', 'year'] = 'year' (period to get balance sheets) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), period, output_format.
get_cash_flowsA
Get cash flows of a company from stock market Args: symbol: str (symbol of the company to get cash flows) period: Literal['quarter', 'year'] = 'year' (period to get cash flows) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), period, output_format.
get_company_dividendsB
Get company dividends from stock market Args: symbol: str output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_company_eventsC
Get company events from stock market Args: symbol: str page_size: int = 10 page: int = 0 output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), page_size, page, output_format.
get_company_insider_dealsB
Get company insider deals from stock market Args: symbol: str output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_company_newsA
Get company news from stock market Args: symbol: str page_size: int = 10 page: int = 0 output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), page_size, page, output_format.
get_company_officersB
Get company officers from stock market Args: symbol: str filter_by: Literal['working', "all", 'resigned'] = 'working' output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), filter_by, output_format.
get_company_overviewC
Get company overview from stock market Args: symbol: str output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_company_ratio_summaryC
Get company ratio summary from stock market Args: symbol: str output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_company_reportsB
Get company reports from stock market Args: symbol: str output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_company_subsidiariesA
Get company subsidiaries from stock market Args: symbol: str filter_by: Literal["all", "subsidiary"] = "all" output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), filter_by, output_format.
get_company_trading_statsB
Get company trading stats from stock market Args: symbol: str output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_exchange_rateB
Get exchange rate of all currency pairs from stock market Args: date: str = None (if None, return today's price. Format: YYYY-MM-DD) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: date, output_format.
get_finance_ratiosB
Get finance ratios of a company from stock market Args: symbol: str (symbol of the company to get finance ratios) period: Literal['quarter', 'year'] = 'year' (period to get finance ratios) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), period, output_format.
get_fund_asset_holdingB
Get asset holding of a fund from stock market Args: symbol: str (symbol of the fund to get asset holding) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_fund_industry_holdingB
Get industry holding of a fund from stock market Args: symbol: str (symbol of the fund to get industry holding) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_fund_top_holdingA
Get top holding of a fund from stock market Args: symbol: str (symbol of the fund to get top holding) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_gold_priceB
Get gold price from stock market Args: date: str = None (if None, return today's price. Format: YYYY-MM-DD) source: Literal['SJC', 'BTMC'] = 'SJC' (source to get gold price) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: date, source, output_format.
get_income_statementsB
Get income statements of a company from stock market
Args:
symbol: str (symbol of the company to get income statements)
period: Literal['quarter', 'year'] = 'year' (period to get income statements)
output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI)
Returns:
pd.DataFrame
Inputs: symbol (required), period, output_format.
get_price_boardB
Get price board from stock market Args: symbols: list[str] (list of symbols to get price board) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbols (required), output_format.
get_quote_history_priceB
Get quote price history of a symbol from stock market Args: symbol: str (symbol to get history price) start_date: str (format: YYYY-MM-DD) end_date: str = None (end date to get history price. None means today) interval: Literal['1m', '5m', '15m', '30m', '1H', '1D', '1W', '1M'] = '1D' (interval to get history price) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), start_date (required), end_date, interval, +2 more.
get_quote_intraday_priceC
Get quote intraday price from stock market Args: symbol: str (symbol to get intraday price) page_size: int = 500 (max: 100000) (number of rows to return) page: int = 1 (page number to get intraday price from) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), page_size, page, output_format.
get_quote_price_depthA
Get quote price depth from stock market Args: symbol: str (symbol to get price depth) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), output_format.
get_quote_price_with_indicatorsB
Get quote price with indicators of a symbol from stock market.
Indicators can be specified with or without parameters:
Simple: "rsi", "macd", "stochastic"
With params: "rsi(window=21)", "macd(fast=12, slow=26, signal=9)"
Inputs: symbol (required), indicators (required), start_date (required), end_date, +3 more.
get_raw_reportB
Get raw report of a company from stock market Args: symbol: str (symbol of the company to get raw report) period: Literal['quarter', 'year'] = 'year' (period to get raw report) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: symbol (required), period, output_format.
list_all_companies_with_detailsB
List all companies from stock market with details Args: output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: output_format.
list_all_fundsA
List all funds from stock market Args: fund_type: Literal['BALANCED', 'BOND', 'STOCK', None ] = None (if None, return funds in all types) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: fund_type, output_format.
list_all_icb_industriesB
List all ICB industries from stock market Args: output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: output_format.
search_fundA
Search fund by name from stock market Args: keyword: str (partial match for fund name to search) output_format: Literal['json', 'dataframe', 'toon'] = 'toon' (output format, 'toon' is optimized for AI) Returns: pd.DataFrame
Inputs: keyword (required), output_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 36 tools
Most tools have distinct purposes, but some overlap exists, e.g., get_all_symbols_by_group and get_all_symbols_by_industry may return similar data for certain groups, and get_all_symbols_detailed vs list_all_companies_with_details could be confused. However, descriptions clarify differences.
All tool names follow a consistent 'get_' or 'list_' prefix with snake_case and descriptive nouns (e.g., get_balance_sheets, list_all_funds). No mixing of styles or ambiguous verbs.
36 tools is on the higher side, but the server covers a broad domain (companies, funds, financials, prices, exchange rates, gold). Each tool addresses a specific data need, so the count is justified, though it could be streamlined slightly.
The tool set covers major data categories like company fundamentals, financial statements, price history, funds, and market data. Missing features like analyst ratings or earnings calendar are minor gaps. CRUD operations are not expected for a read-only data server.
Maintenance
Related MCP Connectors
Vietnam stock market data: HOSE/HNX/UPCOM prices, foreign flow, order book, financials, macro, news.
Vietnam stock market data & portfolios via Finhay Securities OpenAPI.
Vietnam stock market and macro data for AI: prices, financials, macro since 1985, VN-Index forecast
Provide access to Chinese stock market data including historical prices, real-time data, news, andβ¦
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides access to Vietnamese stock market data and APIs from VNDirect, FireAnt, and SSI, including real-time stock prices, market news from CafeF, technical analysis (Doji patterns), and comprehensive stock listings.76MIT
- AlicenseBqualityDmaintenanceProvides access to Vietnam stock market data including real-time quotes, historical prices, company financials, trading statistics, mutual fund information, and exchange rates through the vnstock library.332MIT
- AlicenseBqualityDmaintenanceVietnamese Financial Markets Data MCP Server providing real-time quotes, financials, and technical indicators.3554 npm1MIT
- AlicenseNot gradedqualityDmaintenanceProvides seamless access to Vietnamese stock market data, enabling real-time prices, historical data, company fundamentals, and market analysis through natural language queries.17 npmMIT