Metadata-Version: 2.4
Name: vnstock-mcp
Version: 0.1.0
Summary: Vietnamese Stock Market MCP Server - FastMCP 2.0
License-Expression: MIT
Project-URL: Repository, https://github.com/gahoccode/vnstock-mcp
Keywords: vietnam,stock,market,mcp,fastmcp,financial,vnstock
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: vnstock
Requires-Dist: pyportfolioopt>=1.5.6
Requires-Dist: pandas
Requires-Dist: anthropic>=0.34.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiohttp>=3.8.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

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

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

```json
{
  "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.
