Skip to main content
Glama
VNStock MCP Server

VNStock MCP Server

by ariesanhthu

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

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

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:

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:

  1. Run tests

  2. Create and push a git tag

  3. 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:

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 sync completed successfully in the project root.

    • Verify Python version: python --version and uv python list.

  • Command vnstock-mcp-server not found:

    • 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

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests for new functionality

  5. Run tests: uv run pytest

  6. 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+

Available Tools

33 tools
get_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_shareholdersC
Get company shareholders 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_nav_reportC
Get nav report of a fund from stock market
Args:
    symbol: str (symbol of the fund to get nav report)
    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

    B3.2/5.0

    Scored across 33 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides 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.
      7
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides seamless access to Vietnamese stock market data, enabling real-time prices, historical data, company fundamentals, and market analysis through natural language queries.
      17 npm
      MIT