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

![Deploy to Render](https://render.com/deploy?repo=https://github.com/gahoccode/vnprices-mcp)

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:

Tutorial

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

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:

Quit Claude Desktop completely (Cmd+Q on macOS)
Restart Claude Desktop
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: ```bash

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: ```bash

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

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"]
    }
)

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))]

Rebuild:

docker build -t vnprices-mcp:latest .

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

License

MIT License - Feel free to use and modify.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Test thoroughly
Submit a pull request

Support

For issues or questions:

---

Built with ❤️ for the Vietnamese developer community

vnprices-mcp