ssi-stock

SSI Stock Data MCP is a Python-based MCP server that exposes tools to query VietNam stock intraday data via the SSI FastConnect API. It supports common MCP interactions such as listing securities, retrieving security details, getting index components, and fetching daily or intraday OHLCV data. The server is designed to be run using uv (a fast dependency management tool for Python) and can be integrated into client tools like Claude Desktop, enabling natural language queries over stock data. Tools exposed include get_securities_list, get_securities_details, get_index_components, get_index_list, get_daily_ohlc, get_intraday_ohlc, get_daily_index, and get_stock_price, with API details available in the server source code at src/ssi_stock_mcp_server/server.py. To use it, configure the MCP client with the server’s command and environment variables so the client can securely access the SSI FastConnect service.

• Prerequisites:
  • Python 3.12 or newer
  • uv (for dependency management)
  • Docker (optional, for containerized deployment)
  • Access to SSI FastConnect (register to obtain consumer ID and secret)
• Install using uv and local repository:
  1. Clone the repository: git clone https://github.com/archiephan78/ssi-stock-mcp-server.git
  2. Create and activate a virtual environment with uv: uv venv source .venv/bin/activate # Unix/macOS .\venv\Scripts\activate # Windows
  3. Install the package in editable mode: uv pip install -e .
  4. Set up environment variables (example): FC_DATA_URL=https://fc-data.ssi.com.vn/ FC_DATA_AUTH_TYPE=Bearer FC_DATA_CONSUMER_ID=your_consumer_id FC_DATA_CONSUMER_SECRET=your_consumer_secret
• Local run with uv:
  • Ensure you have your environment configured (see above).
  • Start the server (as part of the MCP client configuration): uv run ssi-stock-mcp-server
• Alternative: Docker (optional)
  • Build or pull the pre-built image and run with environment variables: docker run -p 8000:8000
    -e FC_DATA_CONSUMER_ID=your_id
    -e FC_DATA_CONSUMER_SECRET=your_secret
    ghcr.io/archiephan78/ssi-stock-mcp-server:latest
• Quick client integration (example for Claude Desktop):
  • Add a configuration block pointing to the uv-based command with the appropriate directory and environment variables (as shown in the Quickstart section of the README).

• The MCP depends on SSI FastConnect; ensure you have registered and obtained a consumer ID/secret before running.
• If you plan to run in a Docker container, you can either use the pre-built image or build your own from the repository.
• In Claude Desktop, the environment variables FC_DATA_CONSUMER_ID, FC_DATA_CONSUMER_SECRET, FC_DATA_URL, and FC_DATA_AUTH_TYPE can be passed through the config and environment mapping to the container or process.
• The server currently supports historical and intraday data retrieval; streaming/realtime data support is on the roadmap.
• The project uses uv to manage Python dependencies; consult uv documentation for details on venv and activation across platforms.