Skip to main content
Glama
VNStock Agent MCP Server

VNStock Agent MCP Server

by mrgoonie

VNStock Agent

MCP server and CLI for Vietnamese stock market data. Integrates vnstock with AI tools via Model Context Protocol (MCP).

Features

  • 21 MCP tools for AI assistants (Claude, GPT, etc.)

  • 22 CLI commands for terminal use

  • 3 MCP transports: stdio, SSE, Streamable HTTP

  • Vietnamese stocks, forex, crypto, world indices, mutual funds

  • Historical prices, financials, company info, trading data

Related MCP server: SSI Stock Data MCP Server

Quick Start

Install

pip install vnstock-agent

Or from source:

git clone https://github.com/mrgoonie/vnstock-agent.git
cd vnstock-agent
pip install -e .

Set API Key

export VNSTOCK_API_KEY=your_api_key_here

Get a free API key at vnstocks.com/login.

CLI Usage

# Stock history
vnstock-agent history VNM --start 2025-01-01 --end 2025-03-31

# Company overview
vnstock-agent overview FPT

# Financial statements
vnstock-agent balance-sheet VCB --period quarter
vnstock-agent income VCB --period annual
vnstock-agent cashflow VCB
vnstock-agent ratio VCB

# Market data
vnstock-agent symbols                    # All listed symbols
vnstock-agent group --group VN30         # VN30 stocks
vnstock-agent board "VNM,FPT,ACB,VCB"   # Price board
vnstock-agent industries                 # ICB industries

# Company details
vnstock-agent shareholders FPT
vnstock-agent officers FPT
vnstock-agent news FPT
vnstock-agent events FPT

# Intraday & depth
vnstock-agent intraday VNM --page-size 200

# Global markets
vnstock-agent fx EURUSD --start 2025-01-01
vnstock-agent crypto BTC --start 2025-01-01
vnstock-agent index DJI --start 2025-01-01

# Mutual funds
vnstock-agent funds

# JSON output
vnstock-agent --format json history VNM

MCP Server

stdio (for Claude Desktop, Cursor, etc.)

Add to your MCP client config:

{
  "mcpServers": {
    "vnstock": {
      "command": "vnstock-mcp",
      "env": {
        "VNSTOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

SSE Transport

VNSTOCK_MCP_TRANSPORT=sse VNSTOCK_MCP_PORT=8000 vnstock-mcp

Streamable HTTP Transport

VNSTOCK_MCP_TRANSPORT=http VNSTOCK_MCP_PORT=8000 vnstock-mcp

Or via CLI:

vnstock-agent serve --transport sse --port 8000
vnstock-agent serve --transport http --port 8000

MCP Tools

Tool

Description

stock_history

Historical OHLCV price data

stock_intraday

Today's intraday trading data

stock_price_depth

Order book / bid-ask data

company_overview

Company overview info

company_shareholders

Major shareholders

company_officers

Management team

company_news

Company news

company_events

Dividends, AGM, etc.

financial_balance_sheet

Balance sheet

financial_income_statement

Income statement

financial_cash_flow

Cash flow statement

financial_ratio

P/E, P/B, ROE, ROA, etc.

listing_all_symbols

All listed symbols

listing_symbols_by_group

VN30, HNX30, etc.

listing_symbols_by_exchange

By exchange (HOSE, HNX, UPCOM)

listing_industries

ICB industry classification

trading_price_board

Real-time price board

fx_history

Forex historical data

crypto_history

Cryptocurrency data

world_index_history

World market indices

fund_listing

Mutual fund listing

Environment Variables

Variable

Default

Description

VNSTOCK_API_KEY

(none)

VNStock API key

VNSTOCK_SOURCE

VCI

Default data source (VCI, KBS)

VNSTOCK_MCP_TRANSPORT

stdio

MCP transport (stdio, sse, http)

VNSTOCK_MCP_HOST

0.0.0.0

Server host

VNSTOCK_MCP_PORT

8000

Server port

Development

git clone https://github.com/mrgoonie/vnstock-agent.git
cd vnstock-agent
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

License

MIT

Available Tools

21 tools
company_eventsC

Get company events (dividends, AGM, earnings, etc).

Inputs: symbol (required), source. Returns: result

company_newsB

Get latest news about a company.

Inputs: symbol (required), source. Returns: result

company_officersC

Get company officers / management team.

Inputs: symbol (required), source. Returns: result

company_overviewC

Get company overview information (industry, market cap, description, etc).

Inputs: symbol (required), source. Returns: result

company_shareholdersC

Get major shareholders of a company.

Inputs: symbol (required), source. Returns: result

crypto_historyB

Get cryptocurrency historical price data.

Inputs: end, start, symbol, interval. Returns: result

financial_balance_sheetC

Get balance sheet data for a company.

Inputs: symbol (required), period, source. Returns: result

financial_cash_flowC

Get cash flow statement for a company.

Inputs: symbol (required), period, source. Returns: result

financial_income_statementC

Get income statement data for a company.

Inputs: symbol (required), period, source. Returns: result

financial_ratioB

Get financial ratios (P/E, P/B, ROE, ROA, etc) for a company.

Inputs: symbol (required), period, source. Returns: result

fund_listingB

Get list of open-ended mutual funds available in Vietnam.

Inputs: no named parameters. Returns: result

fx_historyC

Get forex (currency pair) historical price data.

Inputs: end, start, symbol, interval. Returns: result

listing_all_symbolsA

Get all listed stock symbols on Vietnamese exchanges (HOSE, HNX, UPCOM).

Inputs: source. Returns: result

listing_industriesC

Get ICB industry classification for Vietnamese stocks.

Inputs: source. Returns: result

listing_symbols_by_exchangeA

Get stock symbols grouped by exchange (HOSE, HNX, UPCOM).

Inputs: source. Returns: result

listing_symbols_by_groupC

Get stock symbols in a market group.

Inputs: group, source. Returns: result

stock_historyB

Get historical OHLCV price data for a Vietnamese stock.

Inputs: symbol (required), end, start, source, +1 more. Returns: result

stock_intradayB

Get intraday (today's) trading data for a stock.

Inputs: symbol (required), source, page_size. Returns: result

stock_price_depthB

Get order book / price depth (bid/ask levels) for a stock.

Inputs: symbol (required), source. Returns: result

trading_price_boardB

Get real-time price board for multiple stocks.

Inputs: symbols (required), source. Returns: result

world_index_historyC

Get world market index historical data.

Inputs: end, start, symbol, interval. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation3/5

    Most tools are clearly separated by domain (company, stock, financial, listing, etc.), but the three listing tools (all_symbols, by_group, by_exchange) overlap heavily and could cause misselection. Stock history, intraday, and price board also have related purposes, though descriptions help distinguish them.

    Naming Consistency4/5

    All names use lowercase snake_case with a domain prefix, which is predictable. The pattern is not strictly verb_noun (some are noun_noun like 'company_events', some gerund-based like 'listing_all_symbols'), but within each domain the style is uniform and readable.

    Tool Count4/5

    21 tools is slightly above the typical comfortable range, but the server covers a broad domain (Vietnamese equities, forex, crypto, world indices, funds) and each tool addresses a distinct data need. The count feels justified rather than bloated.

    Completeness4/5

    The toolset covers the core lifecycle of market data: company fundamentals, financial statements, price history, intraday data, depth, listings, and news. It also extends to other asset classes. Minor gaps like missing specific company dividend details (subsumed by events) or quote snapshot endpoint are workarounds.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.
      11
      2,324
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants to query Vietnam stock intraday data from SSI FastConnect API, providing access to stock codes, detailed information, index data, and OHLC information through natural language queries.
      17
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Unofficial MCP server providing Vietnamese stock market financial data, enabling natural language interaction with Claude Desktop.
      29 PyPI
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server providing Vietnamese stock market data including historical prices, financial statements, company info, trading data, forex, crypto, world indices, and mutual funds through 21 MCP tools and 22 CLI commands with support for stdio, SSE, and Streamable HTTP transports.
      21
      MIT