Skip to content
Back to search

vnstock-agent

MCP server and CLI for Vietnamese stock market data (vnstock)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mrgoonie--vnstock-agent/badge.svg)](/listings/mrgoonie--vnstock-agent)

HTML

<a href="/listings/mrgoonie--vnstock-agent"><img src="/api/listings/mrgoonie--vnstock-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://vnstocks.com/login).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 171 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # VNStock Agent
  2. 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).
  3. ## Features
  4. - **21 MCP tools** for AI assistants (Claude, GPT, etc.)
  5. - **22 CLI commands** for terminal use
  6. - **3 MCP transports**: stdio, SSE, Streamable HTTP
  7. - Vietnamese stocks, forex, crypto, world indices, mutual funds
  8. - Historical prices, financials, company info, trading data
  9. ## Quick Start
  10. ### Install
  11. ```bash
  12. pip install vnstock-agent
  13. ```
  14. Or from source:
  15. ```bash
  16. git clone https://github.com/mrgoonie/vnstock-agent.git
  17. cd vnstock-agent
  18. pip install -e .
  19. ```
  20. ### Set API Key
  21. ```bash
  22. export VNSTOCK_API_KEY=your_api_key_here
  23. ```
  24. Get a free API key at [vnstocks.com/login](https://vnstocks.com/login).
  25. ## CLI Usage
  26. ```bash
  27. # Stock history
  28. vnstock-agent history VNM --start 2025-01-01 --end 2025-03-31
  29. # Company overview
  30. vnstock-agent overview FPT
  31. # Financial statements
  32. vnstock-agent balance-sheet VCB --period quarter
  33. vnstock-agent income VCB --period annual
  34. vnstock-agent cashflow VCB
  35. vnstock-agent ratio VCB
  36. # Market data
  37. vnstock-agent symbols # All listed symbols
  38. vnstock-agent group --group VN30 # VN30 stocks
  39. vnstock-agent board "VNM,FPT,ACB,VCB" # Price board
  40. vnstock-agent industries # ICB industries
  41. # Company details
  42. vnstock-agent shareholders FPT
  43. vnstock-agent officers FPT
  44. vnstock-agent news FPT
  45. vnstock-agent events FPT
  46. # Intraday & depth
  47. vnstock-agent intraday VNM --page-size 200
  48. # Global markets
  49. vnstock-agent fx EURUSD --start 2025-01-01
  50. vnstock-agent crypto BTC --start 2025-01-01
  51. vnstock-agent index DJI --start 2025-01-01
  52. # Mutual funds
  53. vnstock-agent funds
  54. # JSON output
  55. vnstock-agent --format json history VNM
  56. ```
  57. ## MCP Server
  58. ### stdio (for Claude Desktop, Cursor, etc.)
  59. Add to your MCP client config:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "vnstock": {
  64. "command": "vnstock-mcp",
  65. "env": {
  66. "VNSTOCK_API_KEY": "your_api_key_here"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. ### SSE Transport
  73. ```bash
  74. VNSTOCK_MCP_TRANSPORT=sse VNSTOCK_MCP_PORT=8000 vnstock-mcp
  75. ```
  76. ### Streamable HTTP Transport
  77. ```bash
  78. VNSTOCK_MCP_TRANSPORT=http VNSTOCK_MCP_PORT=8000 vnstock-mcp
  79. ```
  80. Or via CLI:
  81. ```bash
  82. vnstock-agent serve --transport sse --port 8000
  83. vnstock-agent serve --transport http --port 8000
  84. ```
  85. ## MCP Tools
  86. | Tool | Description |
  87. |------|-------------|
  88. | `stock_history` | Historical OHLCV price data |
  89. | `stock_intraday` | Today's intraday trading data |
  90. | `stock_price_depth` | Order book / bid-ask data |
  91. | `company_overview` | Company overview info |
  92. | `company_shareholders` | Major shareholders |
  93. | `company_officers` | Management team |
  94. | `company_news` | Company news |
  95. | `company_events` | Dividends, AGM, etc. |
  96. | `financial_balance_sheet` | Balance sheet |
  97. | `financial_income_statement` | Income statement |
  98. | `financial_cash_flow` | Cash flow statement |
  99. | `financial_ratio` | P/E, P/B, ROE, ROA, etc. |
  100. | `listing_all_symbols` | All listed symbols |
  101. | `listing_symbols_by_group` | VN30, HNX30, etc. |
  102. | `listing_symbols_by_exchange` | By exchange (HOSE, HNX, UPCOM) |
  103. | `listing_industries` | ICB industry classification |
  104. | `trading_price_board` | Real-time price board |
  105. | `fx_history` | Forex historical data |
  106. | `crypto_history` | Cryptocurrency data |
  107. | `world_index_history` | World market indices |
  108. | `fund_listing` | Mutual fund listing |
  109. ## Environment Variables
  110. | Variable | Default | Description |
  111. |----------|---------|-------------|
  112. | `VNSTOCK_API_KEY` | (none) | VNStock API key |
  113. | `VNSTOCK_SOURCE` | `VCI` | Default data source (VCI, KBS) |
  114. | `VNSTOCK_MCP_TRANSPORT` | `stdio` | MCP transport (stdio, sse, http) |
  115. | `VNSTOCK_MCP_HOST` | `0.0.0.0` | Server host |
  116. | `VNSTOCK_MCP_PORT` | `8000` | Server port |
  117. ## Development
  118. ```bash
  119. git clone https://github.com/mrgoonie/vnstock-agent.git
  120. cd vnstock-agent
  121. python -m venv .venv
  122. source .venv/bin/activate
  123. pip install -e ".[dev]"
  124. # Run tests
  125. pytest
  126. # Lint
  127. ruff check src/
  128. ```
  129. ## License
  130. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.