MMCPMarkets
MV

mrgoonie/vnstock-agent

开发工具
100 stars 0 forks 质量 90 趋势 90
Repository Install

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

概览

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

README

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

View this README on GitHub

安装

This server does not publish a one-line install command.

Open the repository installation guide

配置

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