vnstock-mcp 0.1.0

Vietnamese Stock Market MCP Server - FastMCP 2.0

VNStock MCP Server

The unofficial MCP server that provides all the features of vnstock, allowing you to interact with your Claude Desktop using natural language processing capabilities.

Features

• 🚀 Direct MCP Integration: Connect to your vnstock MCP server via stdio
• 🤖 LLM-Powered: Natural language processing with Anthropic Claude
• 💬 Interactive CLI: Rich terminal interface with auto-completion and history
• 📊 Beautiful Output: Formatted tables, charts, and data visualization
• 🔧 Tool Management: Automatic tool discovery and validation
• 🎯 Smart Parsing: Vietnamese stock symbol and date format support
• ⚡ Error Handling: Robust error recovery and user-friendly messages

Quick Start

1. Installation

# Clone or navigate to your vnstock-mcp directory
cd vnstock-mcp

# Install uv if you don't have it
pip install uv

# Install dependencies with uv (recommended)
uv sync

# Or install with pip (legacy method)
pip install -e .

2. Run the Server

# Start the MCP server (recommended with uv)
uv run python server.py

# Or with python directly
python server.py

Usage Examples

> What's the current price of VNM stock?
> Show me FPT's financial statements for 2024
> Get the latest SJC gold price
> What are HPG's key financial ratios?
> Show me dividend history for ACB stock

Project Structure

vnstock-mcp/
├── pyproject.toml          # Project configuration and dependencies
├── server.py               # Main MCP server
├── client.py               # CLI client (if exists)
├── tests/                  # Test suite
├── .venv/                  # uv-managed virtual environment
├── uv.lock                 # Dependency lock file
└── README.md               # This file

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/vnstock-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

Note: Replace /ABSOLUTE/PATH/TO/vnstock-mcp with the actual absolute path to your project directory.

License

This project is part of the vnstock-mcp ecosystem. See the main repository for licensing information.