vnstock-agent

# VNStock Agent MCP server and CLI for Vietnamese stock market data. Integrates [vnstock](https://github.com/thinh-vu/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 ```bash pip install vnstock-agent ``` Or from source: ```bash git clone https://github.com/mrgoonie/vnstock-agent.git cd vnstock-agent pip install -e . ``` ### Set API Key ```bash export VNSTOCK_API_KEY=your_api_key_here ``` Get a free API key at [vnstocks.com/login](https://vnstocks.com/login). ## CLI Usage ```bash # 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: ```json { "mcpServers": { "vnstock": { "command": "vnstock-mcp", "env": { "VNSTOCK_API_KEY": "your_api_key_here" } } } } ``` ### SSE Transport ```bash VNSTOCK_MCP_TRANSPORT=sse VNSTOCK_MCP_PORT=8000 vnstock-mcp ``` ### Streamable HTTP Transport ```bash VNSTOCK_MCP_TRANSPORT=http VNSTOCK_MCP_PORT=8000 vnstock-mcp ``` Or via CLI: ```bash 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 ```bash 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