VN Stock API

You run a dedicated MCP server that lets you search, access, and aggregate VN stock API data from VNDirect, FireAnt, and SSI. It also provides real-time quotes, stock listings, market news, and technical pattern analysis to help you build financial tooling quickly.

How to use

Use an MCP client to connect to the VN stock API MCP server. You can search for API documentation, fetch endpoint lists, access documentation URLs, and run specialized tools to get real-time prices, list Vietnamese stocks, pull market news from CafeF via Firecrawl, and analyze Doji patterns in price data. The server exposes a consistent set of tools you can call with structured inputs to integrate stock data into dashboards, analytics, or trading assistants.

How to install

# Prerequisites: ensure you have Node.js installed (LTS version recommended)
node -v
npm -v

# Option A: Clone the repository and build (recommended for active development)
git clone https://github.com/Long0308/vn-stock-api-mcp.git
cd vn-stock-api-mcp

# Install dependencies and build the project
npm install
npm run build

# Start the MCP server (see configuration section for details)
npm start

# Option B: Use directly from the repository if you just want to run it without development
# Clone the repo
git clone https://github.com/Long0308/vn-stock-api-mcp.git
cd vn-stock-api-mcp

# Install dependencies (dist/ already built in this path)
npm install

# Run the server (start command shown in the configuration examples)
npm start

Configuration and usage notes

Configure how you run the MCP server by creating mcp.json in your environment. The server can be started with a local Node.js process and a path to the built distribution. If you want to enable market news scraping via Firecrawl, include the FIRECRAWL_API_KEY in the environment.

Config examples you can deploy

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\vn-stock-api-mcp\\dist\\index.js"
      ]
    }
  }
}

Config with Firecrawl API key for CafeF market news

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\vn-stock-api-mcp\\dist\\index.js"
      ],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key-here"
      }
    }
  }
}

Config with a relative path

{
  "mcpServers": {
    "vn-stock-api-mcp": {
      "command": "node",
      "args": [
        "~/vn-stock-api-mcp/dist/index.js"
      ],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key-here"
      }
    }
  }
}

Security and keys

Keep your API keys private. Do not commit credentials into version control. If you disable the CafeF news feature, the server will continue to work with other tools.

Notes on tools and features

The MCP server exposes a set of tools to help you access and analyze stock data. Each tool focuses on a specific task and can be combined with others for comprehensive workflows.

Troubleshooting

If a tool cannot retrieve data from a provider, verify network access, API credentials, and that the provider’s service is reachable. For CafeF market news, ensure you have a valid Firecrawl API key if you want full functionality. If you get fallback results, you can still access URLs or perform static lookups.

Development and build commands

npm run dev  # Watch mode for development
npm run build  # Build the distribution
npm start  # Run the MCP server

Available tools

search_vn_stock_api

Search API documentation from providers such as VNDirect, FireAnt, and SSI. Supports keyword based queries.

get_api_endpoints

Retrieve the list of API endpoints for a given provider, with optional category filtering.

get_api_documentation_urls

Fetch API documentation URLs for one or more providers.

get_stock_price_fireant

Get real-time stock prices from FireAnt for one or multiple symbols. If FireAnt is unavailable, returns a URL to access data on FireAnt's site.

list_vn_stocks

List all Vietnamese stock symbols available on HOSE, HNX, and UPCOMM. Optional filters by exchange and search term.

get_cafef_market_news

Scrape and return the latest market news from CafeF using Firecrawl, with optional limit, search, and format parameters.

analyze_doji_pattern

Analyze Doji candlestick patterns on OHLC data for a given symbol, period, and date range. Identifies Standard, Long-legged, Dragonfly, Gravestone, and Four Price Doji.