💰
Vnstock Agent
MCP server and CLI for Vietnamese stock market data (vnstock)
0 installs
Trust: 44 — Fair
Finance
Ask AI about Vnstock Agent
Powered by Claude · Grounded in docs
I know everything about Vnstock Agent. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
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
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
