VNStock Agent Server

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

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