An MCP Server for the vnstock3 library

A Model Context Protocol (MCP) server that provides Vietnamese financial market data through Claude Desktop. Fetch historical prices for stocks, forex, cryptocurrencies, and international indices using the vnstock3 library.

Features

• Vietnamese Stocks: Historical OHLCV data for Vietnamese stock market
• Forex Rates: Exchange rate data for currency pairs
• Cryptocurrencies: Historical crypto price data
• International Indices: Global market index data
• Containerized: Runs as an isolated Docker container via MCP Gateway
• Seamless Integration: Works directly with Claude Desktop

Quick Deploy

Available Tools

Price History Tools

1. get_stock_history

Fetch historical stock price data for Vietnamese stocks (e.g., VCI, VNM, HPG).

2. get_forex_history

Fetch historical forex exchange rate data (e.g., USDVND, EURVND).

3. get_crypto_history

Fetch historical cryptocurrency price data (e.g., BTC, ETH).

4. get_index_history

Fetch historical index data for Vietnamese market indices (VNINDEX, HNXINDEX, UPCOMINDEX).

Portfolio Optimization Tools

5. calculate_returns

Calculate expected returns for a portfolio of Vietnamese stocks using mean historical or exponential moving average methods.

6. optimize_portfolio

Perform Mean-Variance Optimization to find the maximum Sharpe ratio portfolio for Vietnamese stocks.

7. full_portfolio_optimization

Perform comprehensive portfolio optimization with multiple strategies (max Sharpe, min volatility, max utility) for Vietnamese stocks.

Financial Statement Tools

Note: Currently supports annual periods only. Quarterly data support planned for future releases.

8. get_income_statement

Fetch annual income statement (profit & loss) for Vietnamese stocks.

9. get_balance_sheet

Fetch annual balance sheet for Vietnamese stocks.

10. get_cash_flow

Fetch annual cash flow statement for Vietnamese stocks.

11. get_financial_ratios

Fetch annual financial ratios (P/B, ROE, etc.) for Vietnamese stocks.

Dividend Data Tool

12. get_dividend_history

Fetch complete dividend history for Vietnamese stocks.

Company Information Tools

13. get_company_info

Fetch comprehensive company information for Vietnamese stocks including overview, shareholders, officers, subsidiaries, events, news, reports, financial ratios summary, and trading statistics.

Commodity & Exchange Rate Tools

14. get_sjc_gold_price

Fetch SJC gold prices (current or historical from 2016-01-02).

15. get_btmc_gold_price

Fetch BTMC (Bảo Tín Minh Châu) gold prices (current only).

16. get_vcb_exchange_rate

Fetch VCB (Vietcombank) exchange rates for a specific date.

Fund Management Tools

17. get_fund_listing

Get list of all available mutual funds with filtering by fund type (BALANCED, BOND, STOCK).

18. search_funds

Search for mutual funds by symbol or partial name.

19. get_fund_nav_report

Get historical NAV report for a specific mutual fund.

20. get_fund_top_holdings

Get top 10 holdings for a specific mutual fund.

21. get_fund_industry_allocation

Get industry allocation breakdown for a specific mutual fund.

22. get_fund_asset_allocation

Get asset allocation breakdown for a specific mutual fund.

Prerequisites

• Docker Desktop (or Docker Engine) - Download Docker Desktop
• Claude Desktop application
• macOS, Windows, or Linux

vnstock3 Documentation:

• vnstock3 Documentation
• vnstock Historical Prices Guide
• vnstock VCI Quote Source
• vnstock MSN Quote Source

Tutorial

Besides the docs, I highly recommend watching this tutorial and following NetworkChuck's instructions. This guy is awesome!

• Docker MCP Tutorial by NetworkChuck
• NetworkChuck's Docker MCP Example

Project Structure

vnprices-mcp/
├── server.py           # MCP server implementation
├── Dockerfile          # Container definition
├── requirements.txt    # Python dependencies
└── README.md          # This file

Configuration

Step 1: Clone the Repository

First, clone this repository:

git clone https://github.com/gahoccode/vnprices-mcp.git
cd vnprices-mcp

Step 2: Copy Configuration Files

Copy the vnstock catalog and configuration files to the MCP directory:

# Create the catalogs directory if it doesn't exist
mkdir -p ~/.docker/mcp/catalogs

# Copy the catalog file
cp vnstock-catalog.yaml ~/.docker/mcp/catalogs/custom.yaml

# Copy the config file
cp config.yaml ~/.docker/mcp/config.yaml

# Copy the registry file
cp registry.yaml ~/.docker/mcp/registry.yaml

Step 3: Claude Desktop Setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/Users/YOUR_USERNAME/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--transport=stdio"
      ]
    }
  }
}

Important: Replace YOUR_USERNAME with your actual macOS username.

After configuration:

1. Quit Claude Desktop completely (Cmd+Q on macOS)
2. Restart Claude Desktop
3. Wait for it to fully load

Usage Examples

For detailed usage examples and sample queries, see examples/questions.md.

Quick examples:

• Stock Data: Get VCI stock prices from January 1, 2024 to December 31, 2024
• Portfolio Optimization: Find the optimal portfolio weights for VCI, VNM, HPG to maximize Sharpe ratio
• Financial Statements: Get the annual income statement for VCI stock
• Company Info: Show me major shareholders of VCI stock

Rebuild & Test

After Code Changes

If you modify server.py or other files:

# 1. Navigate to project directory
cd vnprices-mcp

# 2. Rebuild Docker image
docker build -t vnprices-mcp:latest .
docker build -t mcp-gateway .

# 2. Stop and remove old gateway container
docker stop mcp-gateway && docker rm mcp-gateway

# 3. Verify new image
docker images | grep vnprices-mcp

# 4. Check image ID changed
docker images vnprices-mcp

# 5. Run gateway
docker run -d \
  --name mcp-gateway \
  -v $(pwd)/catalogs:/mcp/catalogs \
  -v $(pwd)/registry.yaml:/mcp/registry.yaml \
  -v $(pwd)/config.yaml:/mcp/config.yaml \
  -p 3000:3000 \
  mcp-gateway

# 6. Restart Claude Desktop completely
# Quit (Cmd+Q) and restart

View Live Logs

While Claude Desktop is running:

# Find the gateway container
docker ps | grep mcp-gateway

# View logs (replace <container-id> with actual ID)
docker logs -f <container-id>

# Or in one command
docker logs -f $(docker ps -q -f ancestor=docker/mcp-gateway)

Clean Up Old Containers

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune

# Full cleanup (careful!)
docker system prune -a

Force Rebuild Everything

If things aren't working:

# 1. Stop Claude Desktop

# 2. Remove old containers
docker rm -f $(docker ps -aq -f ancestor=vnprices-mcp:latest)
docker rm -f $(docker ps -aq -f ancestor=docker/mcp-gateway)

# 3. Remove old image
docker rmi vnprices-mcp:latest

# 4. Rebuild from scratch
docker build --no-cache -t vnprices-mcp:latest .

# 5. Verify files exist
ls -la ~/.docker/mcp/
cat ~/.docker/mcp/config.yaml
cat ~/.docker/mcp/catalogs/custom.yaml

# 6. Test gateway manually (see above)

# 7. Restart Claude Desktop

Development

Project Structure

vnprices-mcp/
├── server.py              # MCP server implementation
│   ├── handle_list_tools()    # Register available tools
│   └── handle_call_tool()     # Execute tool calls
├── Dockerfile             # Container configuration
├── requirements.txt       # Python dependencies
└── README.md             # Documentation

Adding New Tools

1. Add tool definition in handle_list_tools():

types.Tool(
    name="your_new_tool",
    description="What it does",
    inputSchema={
        "type": "object",
        "properties": {
            "param": {"type": "string"}
        },
        "required": ["param"]
    }
)

2. Add handler logic in handle_call_tool():

elif name == "your_new_tool":
    # Your implementation
    result = {"data": "response"}
    return [types.TextContent(type="text", text=json.dumps(result))]

3. Rebuild:

docker build -t vnprices-mcp:latest .

4. Update catalog in ~/.docker/mcp/catalogs/custom.yaml:

tools:
  - name: your_new_tool

Technical Details

• MCP Protocol Version: 2025-06-18
• Python Version: 3.11
• MCP SDK: 1.2.0+
• VNStock: 3.2.0+
• PyPortfolioOpt: 1.5.6+ (portfolio optimization)
• Transport: stdio (Standard Input/Output)
• Container Size: ~1.7GB (v1.0.0+: increased from ~1.2GB due to portfolio optimization libraries)
• Total Tools: 22 (4 price history + 3 portfolio optimization + 4 financial statements + 1 dividend + 1 company info + 3 commodity/exchange + 6 fund management)

References

• vnstock3 Documentation
• vnstock Historical Prices Guide
• vnstock Financial Statements Guide
• vnstock Financial Statements Data Types
• vnstock Dividends Guide
• vnstock Commodity Prices Guide
• vnstock Gold Price Source
• vnstock Exchange Rate Source
• Model Context Protocol
• MCP Python SDK
• Docker MCP Gateway

License

MIT License - Feel free to use and modify.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test thoroughly
4. Submit a pull request

Support

For issues or questions:

• VNStock: vnstock GitHub
• MCP: Model Context Protocol Docs
• Docker: Docker MCP Gateway

---

Built with ❤️ for the Vietnamese developer community