VNStock MCP Server (Unofficial)

Test Status PyPI version PyPI downloads Python versions License: MIT

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 uv or see https://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-server or vnstock-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:

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 :
- Ensure uv sync completed successfully in the project root.
- Verify Python version: python --version and uv python list.
Command :
- Ensure the package is installed: pip list | grep vnstock-mcp-server
- Try 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 8000
- Try accessing http://127.0.0.1:8000 in 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 --help to see available transport options
- stdio: 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 --version
View all options: vnstock-mcp-server --help
Test server startup: Run with --transport stdio first 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+