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 show me the current price of VIC stock"
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 Agent 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.10+
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 mount path
vnstock-mcp-server --transport sse --mount-path /vnstock
# 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 [--mount-path /path]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-httpServer 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)
-m, --mount-path MOUNT_PATH
Mount path for SSE transport (optional)
-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",
"--mount-path",
"/vnstock"
]
},
"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 mount-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.1.0 (Current Development)
NEW: Added support for multiple transport modes (stdio, sse, streamable-http)
NEW: Command line arguments for transport selection (
--transport,--mount-path)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
33 toolsget_all_industriesC
Get all symbols from stock market
Args:
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame or json
Inputs: output_format.
get_all_symbol_groupsC
Get all symbol groups from stock market
Args:
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: output_format.
get_all_symbolsB
Get all symbols from stock market
Args:
output_format: Literal['json', 'dataframe'] = 'json'
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'] = 'json'
Returns:
pd.DataFrame
Inputs: group (required), output_format.
get_all_symbols_by_industryB
Get all symbols from stock market
Args:
industry: str = None (if None, return all symbols)
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame or json
Inputs: industry, output_format.
get_balance_sheetsB
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), period, output_format.
get_cash_flowsB
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), period, output_format.
get_company_dividendsC
Get company dividends from stock market
Args:
symbol: str
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_company_eventsB
Get company events from stock market
Args:
symbol: str
page_size: int = 10
page: int = 0
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), page_size, page, output_format.
get_company_insider_dealsC
Get company insider deals from stock market
Args:
symbol: str
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_company_newsC
Get company news from stock market
Args:
symbol: str
page_size: int = 10
page: int = 0
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), page_size, page, output_format.
get_company_officersC
Get company officers from stock market
Args:
symbol: str
filter_by: Literal['working', "all", 'resigned'] = 'working'
output_format: Literal['json', 'dataframe'] = 'json'
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'] = 'json'
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_company_reportsC
Get company reports from stock market
Args:
symbol: str
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_company_subsidiariesC
Get company subsidiaries from stock market
Args:
symbol: str
filter_by: Literal["all", "subsidiary"] = "all"
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), filter_by, output_format.
get_company_trading_statsC
Get company trading stats from stock market
Args:
symbol: str
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_exchange_rateA
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'] = 'json'
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), period, output_format.
get_fund_asset_holdingC
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_fund_industry_holdingC
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
get_fund_top_holdingC
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'] = 'json'
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'] = 'json'
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), period, output_format.
get_price_boardC
Get price board from stock market
Args:
symbols: list[str] (list of symbols to get price board)
output_format: Literal['json', 'dataframe'] = 'json'
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), start_date (required), end_date, interval, +1 more.
get_quote_intraday_priceB
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)
last_time: str = None (last time to get intraday price from)
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), page_size, last_time, output_format.
get_quote_price_depthC
Get quote price depth from stock market
Args:
symbol: str (symbol to get price depth)
output_format: Literal['json', 'dataframe'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), output_format.
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'] = 'json'
Returns:
pd.DataFrame
Inputs: symbol (required), period, output_format.
list_all_fundsB
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'] = 'json'
Returns:
pd.DataFrame
Inputs: fund_type, output_format.
search_fundB
Search fund by name from stock market
Args:
keyword: str (partial match for fund name to search)
output_format: Literal['json', 'dataframe'] = 'json'
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 33 tools
Most tools have distinct purposes targeting specific data types (e.g., balance sheets vs. cash flows vs. price history), but there is some potential confusion between 'get_all_symbols', 'get_all_symbols_by_group', and 'get_all_symbols_by_industry' as they all retrieve symbol lists with minor filtering differences. The descriptions help clarify, but the overlap exists.
All tools follow a consistent 'verb_noun' pattern with snake_case, using 'get_' for retrieval, 'list_' for listing, and 'search_' for searching. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming conventions.
With 33 tools, the count is borderline high for a stock market server, potentially overwhelming for agents. While it covers many aspects (symbols, financials, news, funds, etc.), it might benefit from consolidation or categorization to reduce complexity, as 16-25 tools would be more typical for such a scope.
The tool set provides comprehensive coverage for a stock market domain, including symbol retrieval, financial statements (balance sheets, income statements, cash flows), company details (overview, news, events), pricing data (history, intraday, depth), funds, and ancillary data like exchange rates and gold prices. There are no obvious gaps, offering full lifecycle and data access for typical stock analysis workflows.
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
US, Japan and Vietnam market data: macro, sectors, fundamentals, estimates, price history.
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
- AlicenseBqualityDmaintenanceMCP server for Vietnamese stock market data, enabling AI assistants to access stock history, financials, company info, and global market data through 21 tools.21104MIT
- 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
- AlicenseBqualityDmaintenanceProvides tools to access Vietnam stock market data, including stock prices, financial statements, and market statistics.363MIT