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
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-server
Install from source
git clone https://github.com/maobui/vnstock-mcp-server.git
cd vnstock-mcp-server
uv sync
Prerequisites
- 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.server
With 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 --help
The 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 stdio - Best 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-http - 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)
-m, --mount-path MOUNT_PATH
Mount path for SSE transport (optional)
-v, --version Show version information
-h, --help Show help message
MCP 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-server - Args: (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 dev
Testing 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.html
Building and Publishing
Build locally
# Using the build script
./scripts/build.sh
# Or manually
python -m build
Create a release
# Update version in pyproject.toml first, then:
./scripts/release.sh
This 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.
- Ensure
- Command
vnstock-mcp-servernot found:- Ensure the package is installed:
pip list | grep vnstock-mcp-server - Try reinstalling:
pip install --upgrade vnstock-mcp-server
- Ensure the package is installed:
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 8000 - Try 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 options - stdio: for desktop MCP clients (Claude Desktop, Cursor)
- sse: for web applications
- streamable-http: for HTTP API integrations
- Use
Getting Help
- Check server version:
vnstock-mcp-server --version - View all options:
vnstock-mcp-server --help - Test 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 pytest - Submit 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+