Metadata-Version: 2.4
Name: vnstock-mcp
Version: 0.3.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>=3.3.0
Requires-Dist: pandas
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pytz>=2025.2

# VNStock MCP Server

The unofficial MCP server that provides Vietnamese stock market financial data, allowing you to interact with your Claude Desktop using natural language processing capabilities.

## Features

- 🚀 **Dual Transport Support**: Auto-detects STDIO (local) or HTTP (cloud) transport
- ☁️ **Cloud Deployment**: One-click deploy to Render.com free tier
- 🤖 **LLM-Powered**: Natural language processing with Anthropic Claude
- 📊 **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

**For End Users (Recommended)**
```bash
# Install from PyPI and run directly
uvx vnstock-mcp@latest
```

**For Developers**
```bash
# Clone the repository
git clone https://github.com/gahoccode/vnstock-mcp.git
cd vnstock-mcp

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync
```

### 2. Run the Server

**End Users (uvx method)**
```bash
# Run directly from PyPI
uvx vnstock-mcp@latest
```

**Developers (local development)**
```bash
# Run from source
uv run python src/vnstock_mcp/server.py
```

## Usage Examples

```
> Show me FPT's financial statements for 2024
> What are HPG's key financial ratios?
> Get VCB exchange rates for today
```

### Project Structure

```
vnstock-mcp/
├── pyproject.toml          # Project configuration and dependencies
├── src/
│   └── vnstock_mcp/        # Python package
│       ├── __init__.py     # Package initialization
│       ├── server.py       # MCP server (API Layer)
│       ├── config.py       # Configuration constants
│       ├── exceptions.py   # Custom exceptions
│       ├── core/           # Service Layer (business logic)
│       │   ├── base.py     # BaseService with async patterns
│       │   ├── financial.py
│       │   ├── company.py
│       │   └── fund.py
│       ├── models/         # Model Layer (result types)
│       │   ├── base.py     # ServiceResult, DataFrameResult
│       │   ├── financial.py
│       │   ├── company.py
│       │   └── fund.py
│       └── utils/          # Utility functions
│           └── data_transform.py
├── docs/                   # Architecture documentation
│   ├── ARCHITECTURE.md     # System architecture overview
│   └── adr/                # Architecture Decision Records
│       ├── 001-layered-architecture.md
│       ├── 002-result-objects.md
│       └── 003-lazy-imports.md
├── tests/                  # Test suite
│   ├── __init__.py
│   └── conftest.py         # Pytest configuration
├── dist/                   # Built packages
├── sample questions/       # Usage examples
├── uv.lock                 # Dependency lock file
└── README.md               # This file
```

For detailed architecture documentation, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## uv vs uvx: Which to Use?

### **uvx (Recommended for Users)**
- **Purpose**: Run Python packages directly from PyPI
- **Use case**: End users who just want to use the MCP server
- **Command**: `uvx vnstock-mcp@latest`
- **Benefits**:
  - No local setup required
  - Automatic dependency management
  - Isolated execution environment

### **uv (Recommended for Developers)**
- **Purpose**: Python project and package management
- **Use case**: Developers who want to modify/contribute to the code
- **Command**: `uv run python src/vnstock_mcp/server.py`
- **Benefits**:
  - Full source code access
  - Development workflow
  - Ability to make changes

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

**Method 1: Using uvx (if PATH configured)**
```json
{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uvx",
      "args": ["vnstock-mcp"]
    }
  }
}
```

**Method 2: Using uvx (if PATH NOT configured)**
```json
{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": ["vnstock-mcp"]
    }
  }
}
```

**Method 3: Development from source (script path)**
```json
{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/USERNAME/PATH_TO/src/vnstock_mcp",
        "run",
        "server.py"
      ]
    }
  }
}
```

**Method 4: Development from source (Python module)**
```json
{
  "mcpServers": {
    "vnstock-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/USERNAME/PATH_TO/vnstock-mcp",
        "run",
        "python",
        "-m",
        "vnstock_mcp.server"
      ]
    }
  }
}
```

**Note:**
- Replace `YOUR_USERNAME` with your actual username in Method 2
- Replace `USERNAME` and `PATH_TO` with your actual username and path in Method 3 and 4
- After quitting and restarting Claude Desktop, if it still can't detect the mcp server, check if `uvx` is in your PATH. If not, add `~/.local/bin` to your PATH:

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

## Publishing to PyPI

For maintainers, use the automated publish script:

```bash
# Set UV_PUBLISH_TOKEN in .env file, then run:
python dev/publish.py
```

Or publish manually:

```bash
uv publish --token $UV_PUBLISH_TOKEN
```

## License

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