VNStock MCP Server

非官方 MCP 服务，可提供越南股市金融数据，让你通过自然语言处理功能与 Claude Desktop 交互。

功能

• 双传输方式支持：自动检测 STDIO（本地）或 HTTP（云端）传输方式
• 云端部署：一键部署到 Render.com 免费套餐
• 大模型驱动：使用 Anthropic Claude 进行自然语言处理
• 精美输出：格式化表格、图表和数据可视化
• 工具管理：自动发现和验证工具
• 智能解析：支持越南股票代码和日期格式
• 错误处理：可靠的错误恢复机制和易懂的提示信息

快速开始

# Install from PyPI and run directly
uvx vnstock-mcp@latest

使用示例

> Show me FPT's income statements for 2024
> What are HPG's key financial ratios?

数据来源

此服务使用 vnstock 4.x 公共适配器：

• 财务报表和比率使用 Finance(source="KBS")，以确保输出一致的 item、item_id 和期间列。财务标签由数据提供方定义；使用 item_id 可稳定识别指标。
• 公司信息使用 Company(source="VCI")，因为 ratio_summary 和 trading_stats 是 VCI 专属的兼容方法。
• 共同基金数据使用顶层 Fund 适配器。

财务报表和比率响应以指标行和期间列的形式返回：

item | item_id | 2025 | 2024 | 2023 | 2022

vnstock 4.x 不支持公司信息类型 reports，因此已将其移除。

Claude Desktop 集成

要在 Claude Desktop 中使用此 MCP 服务，请将以下配置添加到 Claude Desktop 配置文件中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

方法 1：使用 uvx（已配置 PATH）

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uvx",
      "args": ["vnstock-mcp"]
    }
  }
}

方法 2：使用 uvx（未配置 PATH）

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": ["vnstock-mcp"]
    }
  }
}

方法 3：从源代码开发（脚本路径）

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/USERNAME/PATH_TO/src/vnstock_mcp",
        "run",
        "server.py"
      ]
    }
  }
}

方法 4：从源代码开发（Python 模块）

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/USERNAME/PATH_TO/vnstock-mcp",
        "run",
        "python",
        "-m",
        "vnstock_mcp.server"
      ]
    }
  }
}

方法 5：Docker MCP Gateway（简单方式）

{
  "mcpServers": {
    "MCP_DOCKER": {
      "type": "stdio",
      "command": "docker",
      "args": ["mcp", "gateway", "run"]
    }
  }
}

方法 6：Docker MCP Gateway（显式指定目录/注册表）

{
  "mcpServers": {
    "mcp-toolkit-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/vnstock.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--transport=stdio"
      ]
    }
  }
}

注意：

• 在方法 2 和 6 中，将 YOUR_USERNAME 替换为你的实际用户名
• 在方法 3 和 4 中，将 USERNAME 和 PATH_TO 替换为你的实际用户名和路径
• 方法 5 和 6 需要启用 MCP Toolkit 的 Docker Desktop。详情请参阅设置指南
• 方法 5 让 Docker 自动管理目录；方法 6 则固定指定目录、配置和注册表文件
• 退出并重启 Claude Desktop 后，如果仍无法检测到 mcp 服务，请检查 uvx 是否位于 PATH 中。如果不在，请将 ~/.local/bin 添加到 PATH：

# For zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Claude Code 集成

claude mcp add vnstock-mcp --transport http https://your-app.onrender.com/mcp

远程 MCP 服务

无需在本地安装任何内容，即可连接部署在 Render（或任何云服务提供商）上的 VNStock MCP 服务。远程服务会在 /mcp 提供 Streamable HTTP 端点。

在每个客户端的图形界面中添加远程 MCP 服务时，请使用服务 URL https://your-app.onrender.com/mcp。各客户端的指南：

• Claude Desktop — 通过 Settings > MCP Servers 添加
• Claude Code（CLI） — claude mcp add vnstock-mcp https://your-app.onrender.com/mcp --transport http
• Perplexity — 按照添加自定义远程连接器中的说明操作

**注意：**将 your-app.onrender.com 替换为你的实际 Render 部署 URL，并在末尾添加 /mcp。

你可以使用自定义健康检查端点 /health 验证服务是否正在运行，示例如下：

curl https://your-app.onrender.com/health

如果服务运行于带标签的 git 检出版本，/health 中的 version 字段会报告该标签。对于没有 .git 的打包或部署环境，该字段会回退到已安装软件包的元数据或 VNSTOCK_MCP_VERSION。

开发

请参阅 设置指南，了解如何设置 docker MCP 网关。

项目结构、Docker 构建和部署指南，请参阅 开发指南。

有关修复常见问题的提示，包括快速诊断命令、验证目录、注册表、Claude Config 验证、身份验证和权限，请参阅 故障排除指南。

许可证

本项目是 vnstock 库的封装。有关许可和 API 信息，请参阅主仓库和文档：

• vnstock GitHub 仓库
• vnstock 4.x 发行说明
• vnstock 架构文档