使用说明

vnstock3库的MCP服务器

通过Claude Desktop提供越南金融市场数据的模型上下文协议（MCP）服务器。使用vnstock3库获取股票、外汇、加密货币和国际指数的历史价格。

特性

越南股票：越南股市历史OHLCV数据
外汇汇率：货币对的汇率数据
加密货币：历史加密货币价格数据
国际指数：全球市场指数数据
容器化：通过MCP网关作为隔离的Docker容器运行
无缝集成：直接与Claude Desktop配合使用

快速部署

可用工具

价格历史记录工具

1. `get_stock_history`

获取越南股票的历史股价数据（例如VCI、VNM、HPG）。

2. `get_forex_history`

获取历史外汇汇率数据（例如，USDVND、EURVND）。

3. `get_crypto_history`

获取历史加密货币价格数据（例如BTC、ETH）。

4. `get_index_history`

获取越南市场指数（VNINDEX、HNXINDEX、UPCOMINDEX）的历史指数数据。

投资组合优化工具

5. `calculate_returns`

使用平均历史或指数移动平均法计算越南股票投资组合的预期回报。

6. `optimize_portfolio`

执行均值-方差优化，为越南股票找到最大的夏普比率投资组合。

7. `full_portfolio_optimization`

对越南股票采用多种策略（最大夏普、最小波动、最大效用）进行全面的投资组合优化。

财务报表工具

注：目前仅支持年度期间。计划为未来版本提供季度数据支持。

8. `get_income_statement`

获取越南股票的年度损益表。

9. `get_balance_sheet`

获取越南股票的年度资产负债表。

10. `get_cash_flow`

获取越南股票的年度现金流量表。

11. `get_financial_ratios`

获取越南股票的年度财务比率（P/B、ROE等）。

股息数据工具

12. `get_dividend_history`

获取越南股票的完整股息历史记录。

公司信息工具

13. `get_company_info`

获取越南股票的全面公司信息，包括概述、股东、高级职员、子公司、事件、新闻、报告、财务比率摘要和交易统计数据。

商品和汇率工具

14. `get_sjc_gold_price`

获取SJC黄金价格（2016年1月2日的当前或历史价格）。

15. `get_btmc_gold_price`

获取BTMC（Bảo Tín Minh Châu）黄金价格（仅限当前）。

16. `get_vcb_exchange_rate`

获取特定日期的VCB（Vietcombank）汇率。

基金管理工具

17. `get_fund_listing`

按基金类型（余额、债券、股票）筛选，获取所有可用共同基金的列表。

18. `search_funds`

按符号或部分名称搜索共同基金。

19. `get_fund_nav_report`

获取特定共同基金的历史资产净值报告。

20. `get_fund_top_holdings`

获取特定共同基金的前10大持股。

21. `get_fund_industry_allocation`

获取特定共同基金的行业分配明细。

22. `get_fund_asset_allocation`

获取特定共同基金的资产配置明细。

先决条件

Docker 桌面版 （或Docker引擎）- 下载 Docker Desktop
克劳德桌面 应用
macOS、Windows或Linux

vnstock3文档：

教程

除了文档，我强烈建议您观看本教程并遵循NetworkChuck的说明。这家伙太棒了！

项目结构

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

配置

步骤1：克隆存储库

首先，克隆此存储库：

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

步骤2：复制配置文件

将vnstock目录和配置文件复制到MCP目录：

# 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

步骤3:克劳德桌面设置

编辑 ~/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"
      ]
    }
  }
}

重要提示： 替换 YOUR_USERNAME 使用您的实际macOS用户名。

配置后：

完全退出克劳德桌面（macOS上的Cmd+Q）
重新启动克劳德桌面
等待其完全加载

用法示例

有关详细的使用示例和示例查询，请参阅示例/问题.md.

快速示例：

股票数据: Get VCI stock prices from January 1, 2024 to December 31, 2024
投资组合优化: Find the optimal portfolio weights for VCI, VNM, HPG to maximize Sharpe ratio
财务报表: Get the annual income statement for VCI stock
公司信息: Show me major shareholders of VCI stock

重建和测试

代码更改后

如果你修改 server.py 或其他文件：

# 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

查看实时日志

当Claude Desktop正在运行时：

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

清理旧容器

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune

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

强制重建一切

如果事情不起作用：

# 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

发展

项目结构

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

添加新工具

添加工具定义 在 handle_list_tools():

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

添加处理程序逻辑 在 handle_call_tool():

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

重建：

docker build -t vnprices-mcp:latest .

更新目录 在 ~/.docker/mcp/catalogs/custom.yaml:

tools:
  - name: your_new_tool

技术细节

MCP协议版本: 2025-06-18
Python 版本: 3.11
MCP-SDK: 1.2.0+
VNStock: 3.2.0+
PyPortfolioOpt：1.5.6+（投资组合优化）
运输：stdio（标准输入/输出）
柜型：~1.7GB（v1.0.0+：由于组合优化库，从~1.2GB增加）
工具总数：22（4个价格历史+3个投资组合优化+4个财务报表+1个股息+1个公司信息+3个商品/交易所+6个基金管理）

参考文献

许可证

MIT许可证-请随意使用和修改。

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
彻底测试
提交拉取请求

支持

对于问题或疑问：

内置❤️ 面向越南开发者社区

使用说明

vnstock3库的MCP服务器

特性

快速部署

可用工具

价格历史记录工具

1. get_stock_history

2. get_forex_history

3. get_crypto_history

4. get_index_history

投资组合优化工具

5. calculate_returns

6. optimize_portfolio

7. full_portfolio_optimization

财务报表工具

8. get_income_statement

9. get_balance_sheet

10. get_cash_flow

11. get_financial_ratios

股息数据工具

12. get_dividend_history

公司信息工具

13. get_company_info

商品和汇率工具

14. get_sjc_gold_price

15. get_btmc_gold_price

16. get_vcb_exchange_rate

基金管理工具

17. get_fund_listing

18. search_funds

19. get_fund_nav_report

20. get_fund_top_holdings

21. get_fund_industry_allocation

22. get_fund_asset_allocation

先决条件

教程

项目结构

配置

步骤1：克隆存储库

步骤2：复制配置文件

步骤3:克劳德桌面设置

用法示例

重建和测试

代码更改后

查看实时日志

清理旧容器

强制重建一切

发展

项目结构

添加新工具

技术细节

参考文献

许可证

贡献

支持

相关 MCP

加密货币交易所集成服务

实时金融新闻分析服务

金融数据服务

加密货币查询服务

加密货币情绪指数服务

AI代理金融工具包

1. `get_stock_history`

2. `get_forex_history`

3. `get_crypto_history`

4. `get_index_history`

5. `calculate_returns`

6. `optimize_portfolio`

7. `full_portfolio_optimization`

8. `get_income_statement`

9. `get_balance_sheet`

10. `get_cash_flow`

11. `get_financial_ratios`

12. `get_dividend_history`

13. `get_company_info`

14. `get_sjc_gold_price`

15. `get_btmc_gold_price`

16. `get_vcb_exchange_rate`

17. `get_fund_listing`

18. `search_funds`

19. `get_fund_nav_report`

20. `get_fund_top_holdings`

21. `get_fund_industry_allocation`

22. `get_fund_asset_allocation`