| Name | vnstock-mcp-server JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | An MCP server exposing tools to access Vietnam stock market data built on top of vnstock and mcp |
| upload_time | 2025-09-12 14:44:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
mcp
vnstock
vietnam
stock
market
finance
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# VNStock MCP Server (Unofficial)
An **unofficial** MCP (Model Context Protocol) server that provides tools to access Vietnam stock market data. This is a wrapper around the excellent [vnstock](https://github.com/thinh-vu/vnstock) library by [@thinh-vu](https://github.com/thinh-vu).
> **Note**: This is an independent project and is not officially affiliated with the vnstock library or its maintainers.
## About vnstock
This MCP server is built on top of the [vnstock library](https://github.com/thinh-vu/vnstock) - a powerful Python toolkit for Vietnamese stock market analysis created by Thinh Vu. vnstock provides comprehensive access to Vietnam stock market data including:
- Real-time and historical stock prices
- Company financial statements
- Market data and trading statistics
- Mutual fund information
- Gold prices and exchange rates
For more information about the underlying library, visit: https://github.com/thinh-vu/vnstock
## Features
This MCP server exposes vnstock's capabilities through MCP tools, allowing AI assistants and other MCP clients to:
- Access company information and financial data
- Retrieve stock quotes and historical prices
- Get trading statistics and market data
- Query mutual fund information
- Access gold prices and exchange rates
- Retrieve financial statements (income, balance sheet, cash flow)
## Installation
### Install from PyPI (Recommended)
```bash
pip install vnstock-mcp-server
```
### Install from source
```bash
git clone https://github.com/maobui/vnstock-mcp-server.git
cd vnstock-mcp-server
uv sync
```
## Prerequisites
- Python 3.10+
- uv (install with `pip install uv` or see `https://docs.astral.sh/uv/`)
## Quick Start
### Run the MCP server
#### Default mode (stdio)
```bash
# If installed from PyPI
vnstock-mcp-server
# If installed from source with uv
uv run python -m vnstock_mcp.server
```
#### With transport options
```bash
# Use stdio transport (default)
vnstock-mcp-server --transport stdio
# Use Server-Sent Events (SSE) transport for web applications
vnstock-mcp-server --transport sse
# Use SSE with custom mount path
vnstock-mcp-server --transport sse --mount-path /vnstock
# Use HTTP streaming transport
vnstock-mcp-server --transport streamable-http
# Show help with all available options
vnstock-mcp-server --help
```
The server uses `FastMCP` and supports multiple transport protocols:
- **stdio**: Standard input/output (default, for MCP clients like Claude Desktop)
- **sse**: Server-Sent Events (for web applications)
- **streamable-http**: HTTP streaming (for HTTP-based integrations)
## Transport Modes
The VNStock MCP Server supports three different transport protocols to accommodate various use cases:
### stdio (Default)
- **Use case**: Standard MCP clients like Claude Desktop, Cursor, Cline
- **Protocol**: Communication via standard input/output streams
- **Usage**: `vnstock-mcp-server` or `vnstock-mcp-server --transport stdio`
- **Best for**: Desktop applications and traditional MCP integrations
### SSE (Server-Sent Events)
- **Use case**: Web applications that need real-time data streaming
- **Protocol**: HTTP-based server-sent events
- **Usage**: `vnstock-mcp-server --transport sse [--mount-path /path]`
- **Server runs on**: `http://127.0.0.1:8000` (default)
- **Best for**: Web dashboards, browser-based applications
### streamable-http
- **Use case**: HTTP-based integrations and API services
- **Protocol**: HTTP streaming with JSON-RPC over HTTP
- **Usage**: `vnstock-mcp-server --transport streamable-http`
- **Server runs on**: `http://127.0.0.1:8000` (default)
- **Best for**: REST API integrations, microservices architecture
### Command Line Options
```bash
vnstock-mcp-server [OPTIONS]
Options:
-t, --transport {stdio,sse,streamable-http}
Transport protocol to use (default: stdio)
-m, --mount-path MOUNT_PATH
Mount path for SSE transport (optional)
-v, --version Show version information
-h, --help Show help message
```
## MCP client integration
### Cursor / Cline example
Add a server entry in your MCP configuration:
#### Default stdio transport
```json
{
"mcpServers": {
"vnstock": {
"command": "vnstock-mcp-server"
}
}
}
```
#### With specific transport options
```json
{
"mcpServers": {
"vnstock-sse": {
"command": "vnstock-mcp-server",
"args": ["--transport", "sse", "--mount-path", "/vnstock"]
},
"vnstock-http": {
"command": "vnstock-mcp-server",
"args": ["--transport", "streamable-http"]
}
}
}
```
If installed from source:
```json
{
"mcpServers": {
"vnstock": {
"command": "uv",
"args": ["run", "python", "-m", "vnstock_mcp.server"],
"env": {}
},
"vnstock-sse": {
"command": "uv",
"args": ["run", "python", "-m", "vnstock_mcp.server", "--transport", "sse"],
"env": {}
}
}
}
```
### Claude Desktop example
In MCP server settings:
- Command: `vnstock-mcp-server`
- Args: (leave empty for stdio, or add transport options like `--transport sse`)
## Available Tools
The MCP server provides the following categories of tools:
### Company Information
- Company overview, news, events
- Shareholders and officers information
- Subsidiaries and insider deals
- Trading statistics and ratios
### Financial Data
- Income statements, balance sheets, cash flows
- Financial ratios and raw reports
- Historical financial data (quarterly/yearly)
### Market Data
- Real-time quotes and historical prices
- Intraday trading data and price depth
- Market price boards for multiple symbols
### Fund Information
- Fund listings and search
- NAV reports and holdings
- Industry and asset allocation
### Miscellaneous
- Gold prices (SJC, BTMC)
- Exchange rates
- Symbol listings by industry/group
## Development
### Install with uv (for development)
```bash
# From the project root
uv sync
# Include dev dependencies (for tests and coverage)
uv sync --group dev
```
### Testing with uv
```bash
# Run all tests
uv run pytest
# Run a specific test file
uv run pytest test/test_company_tools.py
# Run with coverage (HTML)
uv run pytest --cov=src/vnstock_mcp --cov-report=html
# Open report:
# ./htmlcov/index.html
```
### Building and Publishing
#### Build locally
```bash
# Using the build script
./scripts/build.sh
# Or manually
python -m build
```
#### Create a release
```bash
# Update version in pyproject.toml first, then:
./scripts/release.sh
```
This will:
1. Run tests
2. Create and push a git tag
3. Trigger GitHub Actions to build and publish to PyPI
## Credits
This project is a wrapper around the [vnstock library](https://github.com/thinh-vu/vnstock) created by [@thinh-vu](https://github.com/thinh-vu). All stock market data access functionality is provided by vnstock.
Please consider:
- ⭐ Starring the original [vnstock repository](https://github.com/thinh-vu/vnstock)
- 📖 Reading the [vnstock documentation](https://vnstocks.com/docs)
- 💖 Supporting the vnstock project if you find it valuable
## Disclaimer
This is an unofficial wrapper and is not affiliated with the vnstock library or its maintainers. For issues related to the underlying stock market data or vnstock functionality, please refer to the [vnstock repository](https://github.com/thinh-vu/vnstock).
## Troubleshooting
### Installation Issues
- **Module not found with `uv run`**:
- Ensure `uv sync` completed successfully in the project root.
- Verify Python version: `python --version` and `uv python list`.
- **Command `vnstock-mcp-server` not found**:
- Ensure the package is installed: `pip list | grep vnstock-mcp-server`
- Try reinstalling: `pip install --upgrade vnstock-mcp-server`
### Connection Issues
- **MCP client cannot connect (stdio mode)**:
- Confirm the client configuration matches the installation method
- Check client logs for detailed errors.
- Ensure no extra arguments are passed for stdio transport
- **Cannot access SSE/HTTP endpoints**:
- Verify the server is running: check for "Uvicorn running on http://127.0.0.1:8000"
- Check if port 8000 is available: `netstat -an | grep 8000`
- Try accessing `http://127.0.0.1:8000` in browser for SSE mode
### Transport Mode Issues
- **SSE transport not working**:
- Ensure mount-path is correctly specified if needed
- Check server logs for startup errors
- Verify web client can connect to the SSE endpoint
- **Wrong transport mode selected**:
- Use `--help` to see available transport options
- stdio: for desktop MCP clients (Claude Desktop, Cursor)
- sse: for web applications
- streamable-http: for HTTP API integrations
### Getting Help
- **Check server version**: `vnstock-mcp-server --version`
- **View all options**: `vnstock-mcp-server --help`
- **Test server startup**: Run with `--transport stdio` first to verify basic functionality
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run tests: `uv run pytest`
6. Submit a pull request
## Changelog
### v1.1.0 (Current Development)
- **NEW**: Added support for multiple transport modes (stdio, sse, streamable-http)
- **NEW**: Command line arguments for transport selection (`--transport`, `--mount-path`)
- **NEW**: SSE (Server-Sent Events) transport for web applications
- **NEW**: HTTP streaming transport for API integrations
- **IMPROVED**: Enhanced CLI with help messages and validation
- **IMPROVED**: Better error handling and user feedback
- **IMPROVED**: Comprehensive documentation for all transport modes
### v1.0.0
- Initial release
- Full Vietnam stock market data access via MCP
- Support for company data, financial statements, quotes, and more
- Wrapper around vnstock v3.2.6+
Raw data
{
"_id": null,
"home_page": null,
"name": "vnstock-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, vnstock, vietnam, stock, market, finance",
"author": null,
"author_email": "Mao Bui <maonguyen199873@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d9/59/f2767723c6eaa898d4284d23a8ca72ceebe3ebf69aacd2358762caea824b/vnstock_mcp_server-1.0.1.tar.gz",
"platform": null,
"description": "# VNStock MCP Server (Unofficial)\n\nAn **unofficial** MCP (Model Context Protocol) server that provides tools to access Vietnam stock market data. This is a wrapper around the excellent [vnstock](https://github.com/thinh-vu/vnstock) library by [@thinh-vu](https://github.com/thinh-vu).\n\n> **Note**: This is an independent project and is not officially affiliated with the vnstock library or its maintainers.\n\n## About vnstock\n\nThis MCP server is built on top of the [vnstock library](https://github.com/thinh-vu/vnstock) - a powerful Python toolkit for Vietnamese stock market analysis created by Thinh Vu. vnstock provides comprehensive access to Vietnam stock market data including:\n\n- Real-time and historical stock prices\n- Company financial statements\n- Market data and trading statistics\n- Mutual fund information\n- Gold prices and exchange rates\n\nFor more information about the underlying library, visit: https://github.com/thinh-vu/vnstock\n\n## Features\n\nThis MCP server exposes vnstock's capabilities through MCP tools, allowing AI assistants and other MCP clients to:\n\n- Access company information and financial data\n- Retrieve stock quotes and historical prices\n- Get trading statistics and market data\n- Query mutual fund information\n- Access gold prices and exchange rates\n- Retrieve financial statements (income, balance sheet, cash flow)\n\n## Installation\n\n### Install from PyPI (Recommended)\n```bash\npip install vnstock-mcp-server\n```\n\n### Install from source\n```bash\ngit clone https://github.com/maobui/vnstock-mcp-server.git\ncd vnstock-mcp-server\nuv sync\n```\n\n## Prerequisites\n- Python 3.10+\n- uv (install with `pip install uv` or see `https://docs.astral.sh/uv/`)\n\n## Quick Start\n\n### Run the MCP server\n\n#### Default mode (stdio)\n```bash\n# If installed from PyPI\nvnstock-mcp-server\n\n# If installed from source with uv\nuv run python -m vnstock_mcp.server\n```\n\n#### With transport options\n```bash\n# Use stdio transport (default)\nvnstock-mcp-server --transport stdio\n\n# Use Server-Sent Events (SSE) transport for web applications\nvnstock-mcp-server --transport sse\n\n# Use SSE with custom mount path\nvnstock-mcp-server --transport sse --mount-path /vnstock\n\n# Use HTTP streaming transport\nvnstock-mcp-server --transport streamable-http\n\n# Show help with all available options\nvnstock-mcp-server --help\n```\n\nThe server uses `FastMCP` and supports multiple transport protocols:\n- **stdio**: Standard input/output (default, for MCP clients like Claude Desktop)\n- **sse**: Server-Sent Events (for web applications)\n- **streamable-http**: HTTP streaming (for HTTP-based integrations)\n\n## Transport Modes\n\nThe VNStock MCP Server supports three different transport protocols to accommodate various use cases:\n\n### stdio (Default)\n- **Use case**: Standard MCP clients like Claude Desktop, Cursor, Cline\n- **Protocol**: Communication via standard input/output streams\n- **Usage**: `vnstock-mcp-server` or `vnstock-mcp-server --transport stdio`\n- **Best for**: Desktop applications and traditional MCP integrations\n\n### SSE (Server-Sent Events)\n- **Use case**: Web applications that need real-time data streaming\n- **Protocol**: HTTP-based server-sent events\n- **Usage**: `vnstock-mcp-server --transport sse [--mount-path /path]`\n- **Server runs on**: `http://127.0.0.1:8000` (default)\n- **Best for**: Web dashboards, browser-based applications\n\n### streamable-http\n- **Use case**: HTTP-based integrations and API services\n- **Protocol**: HTTP streaming with JSON-RPC over HTTP\n- **Usage**: `vnstock-mcp-server --transport streamable-http`\n- **Server runs on**: `http://127.0.0.1:8000` (default)\n- **Best for**: REST API integrations, microservices architecture\n\n### Command Line Options\n```bash\nvnstock-mcp-server [OPTIONS]\n\nOptions:\n -t, --transport {stdio,sse,streamable-http}\n Transport protocol to use (default: stdio)\n -m, --mount-path MOUNT_PATH\n Mount path for SSE transport (optional)\n -v, --version Show version information\n -h, --help Show help message\n```\n\n## MCP client integration\n\n### Cursor / Cline example\nAdd a server entry in your MCP configuration:\n\n#### Default stdio transport\n```json\n{\n \"mcpServers\": {\n \"vnstock\": {\n \"command\": \"vnstock-mcp-server\"\n }\n }\n}\n```\n\n#### With specific transport options\n```json\n{\n \"mcpServers\": {\n \"vnstock-sse\": {\n \"command\": \"vnstock-mcp-server\",\n \"args\": [\"--transport\", \"sse\", \"--mount-path\", \"/vnstock\"]\n },\n \"vnstock-http\": {\n \"command\": \"vnstock-mcp-server\", \n \"args\": [\"--transport\", \"streamable-http\"]\n }\n }\n}\n```\n\nIf installed from source:\n```json\n{\n \"mcpServers\": {\n \"vnstock\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"-m\", \"vnstock_mcp.server\"],\n \"env\": {}\n },\n \"vnstock-sse\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"python\", \"-m\", \"vnstock_mcp.server\", \"--transport\", \"sse\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Claude Desktop example\nIn MCP server settings:\n- Command: `vnstock-mcp-server`\n- Args: (leave empty for stdio, or add transport options like `--transport sse`)\n\n## Available Tools\n\nThe MCP server provides the following categories of tools:\n\n### Company Information\n- Company overview, news, events\n- Shareholders and officers information\n- Subsidiaries and insider deals\n- Trading statistics and ratios\n\n### Financial Data\n- Income statements, balance sheets, cash flows\n- Financial ratios and raw reports\n- Historical financial data (quarterly/yearly)\n\n### Market Data\n- Real-time quotes and historical prices\n- Intraday trading data and price depth\n- Market price boards for multiple symbols\n\n### Fund Information\n- Fund listings and search\n- NAV reports and holdings\n- Industry and asset allocation\n\n### Miscellaneous\n- Gold prices (SJC, BTMC)\n- Exchange rates\n- Symbol listings by industry/group\n\n## Development\n\n### Install with uv (for development)\n```bash\n# From the project root\nuv sync\n\n# Include dev dependencies (for tests and coverage)\nuv sync --group dev\n```\n\n### Testing with uv\n```bash\n# Run all tests\nuv run pytest\n\n# Run a specific test file\nuv run pytest test/test_company_tools.py\n\n# Run with coverage (HTML)\nuv run pytest --cov=src/vnstock_mcp --cov-report=html\n# Open report:\n# ./htmlcov/index.html\n```\n\n### Building and Publishing\n\n#### Build locally\n```bash\n# Using the build script\n./scripts/build.sh\n\n# Or manually\npython -m build\n```\n\n#### Create a release\n```bash\n# Update version in pyproject.toml first, then:\n./scripts/release.sh\n```\n\nThis will:\n1. Run tests\n2. Create and push a git tag\n3. Trigger GitHub Actions to build and publish to PyPI\n\n## Credits\n\nThis project is a wrapper around the [vnstock library](https://github.com/thinh-vu/vnstock) created by [@thinh-vu](https://github.com/thinh-vu). All stock market data access functionality is provided by vnstock.\n\nPlease consider:\n- \u2b50 Starring the original [vnstock repository](https://github.com/thinh-vu/vnstock)\n- \ud83d\udcd6 Reading the [vnstock documentation](https://vnstocks.com/docs)\n- \ud83d\udc96 Supporting the vnstock project if you find it valuable\n\n## Disclaimer\n\nThis is an unofficial wrapper and is not affiliated with the vnstock library or its maintainers. For issues related to the underlying stock market data or vnstock functionality, please refer to the [vnstock repository](https://github.com/thinh-vu/vnstock).\n\n## Troubleshooting\n\n### Installation Issues\n- **Module not found with `uv run`**:\n - Ensure `uv sync` completed successfully in the project root.\n - Verify Python version: `python --version` and `uv python list`.\n- **Command `vnstock-mcp-server` not found**:\n - Ensure the package is installed: `pip list | grep vnstock-mcp-server`\n - Try reinstalling: `pip install --upgrade vnstock-mcp-server`\n\n### Connection Issues\n- **MCP client cannot connect (stdio mode)**:\n - Confirm the client configuration matches the installation method\n - Check client logs for detailed errors.\n - Ensure no extra arguments are passed for stdio transport\n- **Cannot access SSE/HTTP endpoints**:\n - Verify the server is running: check for \"Uvicorn running on http://127.0.0.1:8000\"\n - Check if port 8000 is available: `netstat -an | grep 8000`\n - Try accessing `http://127.0.0.1:8000` in browser for SSE mode\n\n### Transport Mode Issues\n- **SSE transport not working**:\n - Ensure mount-path is correctly specified if needed\n - Check server logs for startup errors\n - Verify web client can connect to the SSE endpoint\n- **Wrong transport mode selected**:\n - Use `--help` to see available transport options\n - stdio: for desktop MCP clients (Claude Desktop, Cursor)\n - sse: for web applications\n - streamable-http: for HTTP API integrations\n\n### Getting Help\n- **Check server version**: `vnstock-mcp-server --version`\n- **View all options**: `vnstock-mcp-server --help`\n- **Test server startup**: Run with `--transport stdio` first to verify basic functionality\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Run tests: `uv run pytest`\n6. Submit a pull request\n\n## Changelog\n\n### v1.1.0 (Current Development)\n- **NEW**: Added support for multiple transport modes (stdio, sse, streamable-http)\n- **NEW**: Command line arguments for transport selection (`--transport`, `--mount-path`)\n- **NEW**: SSE (Server-Sent Events) transport for web applications\n- **NEW**: HTTP streaming transport for API integrations\n- **IMPROVED**: Enhanced CLI with help messages and validation\n- **IMPROVED**: Better error handling and user feedback\n- **IMPROVED**: Comprehensive documentation for all transport modes\n\n### v1.0.0\n- Initial release\n- Full Vietnam stock market data access via MCP\n- Support for company data, financial statements, quotes, and more\n- Wrapper around vnstock v3.2.6+\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An MCP server exposing tools to access Vietnam stock market data built on top of vnstock and mcp",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/MaoBui2907/vnstock-mcp-server",
"Issues": "https://github.com/MaoBui2907/vnstock-mcp-server",
"Repository": "https://github.com/MaoBui2907/vnstock-mcp-server"
},
"split_keywords": [
"mcp",
" vnstock",
" vietnam",
" stock",
" market",
" finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "549c98534a762860c68553a398a3d0dccf90a660dcf5425ff5d9c127cbe37b99",
"md5": "887dca03ac68849ec29747ac4391dfc6",
"sha256": "cfdd392bd81d163c7b42b4d3118db85fbd374caf02204a9139a6aa5563336c4a"
},
"downloads": -1,
"filename": "vnstock_mcp_server-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "887dca03ac68849ec29747ac4391dfc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10031,
"upload_time": "2025-09-12T14:44:55",
"upload_time_iso_8601": "2025-09-12T14:44:55.395287Z",
"url": "https://files.pythonhosted.org/packages/54/9c/98534a762860c68553a398a3d0dccf90a660dcf5425ff5d9c127cbe37b99/vnstock_mcp_server-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d959f2767723c6eaa898d4284d23a8ca72ceebe3ebf69aacd2358762caea824b",
"md5": "077796b44a815f9c29b59469a20c75de",
"sha256": "805e477d63401a8c10bae8b15789838de21f4785e0bbdd78e877196763a6333d"
},
"downloads": -1,
"filename": "vnstock_mcp_server-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "077796b44a815f9c29b59469a20c75de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 24858,
"upload_time": "2025-09-12T14:44:56",
"upload_time_iso_8601": "2025-09-12T14:44:56.954293Z",
"url": "https://files.pythonhosted.org/packages/d9/59/f2767723c6eaa898d4284d23a8ca72ceebe3ebf69aacd2358762caea824b/vnstock_mcp_server-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 14:44:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaoBui2907",
"github_project": "vnstock-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "vnstock-mcp-server"
}
