Metadata-Version: 2.4
Name: vnstock-mcp-advanced
Version: 0.2.1
Summary: MCP server exposing Vietnamese stock market data via vnstock libraries
Project-URL: Homepage, https://github.com/pqhung3007/vnstock-mcp-advanced
Project-URL: Repository, https://github.com/pqhung3007/vnstock-mcp-advanced
Project-URL: Issues, https://github.com/pqhung3007/vnstock-mcp-advanced/issues
Author: pqhung3007
License: MIT
Keywords: fastmcp,finance,mcp,stock,vietnam,vnstock
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0
Requires-Dist: pandas
Requires-Dist: psutil
Requires-Dist: pydantic
Requires-Dist: requests
Requires-Dist: vnai>=2.3.9
Requires-Dist: vnstock
Description-Content-Type: text/markdown

# vnstock-mcp-advanced

An MCP (Model Context Protocol) server that exposes Vietnamese stock market data via the [vnstock](https://github.com/thinh-vu/vnstock) libraries to Claude Desktop, Claude Code, Cursor, Windsurf, and any other MCP-compatible client.

Ships ~60 tools covering core market data, company intelligence, trading flows, macro indicators, commodities, plus composite analyses and professional-grade screeners.

## Install

With [uv](https://docs.astral.sh/uv/) (recommended — no permanent install needed):

```bash
uvx vnstock-mcp-advanced
```

Or with pip:

```bash
pip install vnstock-mcp-advanced
vnstock-mcp-advanced
```

## Configuration

| Env var | Description | Default |
| --- | --- | --- |
| `VNSTOCK_USER_TIER` | `free`, `bronze`, `silver`, or `golden` | `free` |
| `VNSTOCK_API_KEY` | Optional API key (higher rate limits) | _unset_ |

Sponsored tiers (bronze/silver/golden) unlock additional tools such as foreign/prop trading flows, macro indicators, commodities, and the insights screener. All libraries (`vnstock` + `vnstock_data`) are bundled — one install gets everything. Your API key and tier control which features are available at runtime.

## Claude Desktop

Add to `claude_desktop_config.json`:

**Free tier** (no API key needed):
```json
{
  "mcpServers": {
    "vnstock": {
      "command": "uvx",
      "args": ["vnstock-mcp-advanced"],
      "env": {
        "VNSTOCK_USER_TIER": "free"
      }
    }
  }
}
```

**Sponsored tiers** (set your tier and API key):
```json
{
  "mcpServers": {
    "vnstock": {
      "command": "uvx",
      "args": ["vnstock-mcp-advanced"],
      "env": {
        "VNSTOCK_USER_TIER": "bronze",
        "VNSTOCK_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Claude Code

```bash
claude mcp add vnstock -- uvx vnstock-mcp-advanced
```

## License

MIT
