MCP Server for Shioaji

You learn how to run an MCP server that exposes Shioaji trading API capabilities to AI assistants. This enables models to fetch real-time prices, historical data, and stock lists from Taiwan’s market through a simple, MCP-compatible interface.

How to use

You connect an MCP client to the server running on your machine or host, then call the available tools to retrieve data or perform actions. The server exposes tools for getting current stock prices, retrieving historical K-bar data, and scanning stocks by different ranking criteria. Use these tools in your MCP client to compose prompts for AI assistants, automate data retrieval, or power decision-support workflows.

How to install

Prerequisites you need to meet before running the server are Python 3.10 or higher and uv, a fast Python package manager.

# Install uv if you don’t have it yet
pip install uvx
# Or ensure uv is available in your environment according to your setup

Start by configuring credentials for Shioaji. You can either set environment variables or use a .env file in the root directory.

# Option 1: Environment Variables
export SHIOAJI_API_KEY="your_api_key"
export SHIOAJI_SECRET_KEY="your_secret_key"

# Option 2: .env file
# Create a .env file containing:
# SHIOAJI_API_KEY=your_api_key
# SHIOAJI_SECRET_KEY=your_secret_key

Run the MCP server using uv. By default, it will listen on http://0.0.0.0:8000.

uv run mcp-server-shioaji

Configuration and runtime notes

The server expects credentials to access the Shioaji API. You can provide them via environment variables or a .env file as shown above. The server starts with the MCP entry point named mcp-server-shioaji and runs under uv with the default listening address and port.

Security considerations

Keep your API credentials secure. Do not hard-code keys into your codebase. Use environment variables or secret management tools in production to load the SHIOAJI_API_KEY and SHIOAJI_SECRET_KEY at runtime.

Troubleshooting tips

If the server fails to start, verify that Python 3.10+ is installed and that uvx is accessible. Ensure the environment variables (or .env) contain valid Shioaji credentials and that no other process is occupying port 8000.

Available tools

get_stock_price

Retrieve the current price data for one or more stock symbols, including open, high, low, close, volume, and other related trading metrics.

get_kbars

Fetch K-bar (candlestick) data for a specific stock over a date range, returning O, H, L, C values for each period.

scan_stocks

Scan and rank stocks by various criteria such as VolumeRank, AmountRank, TickCountRank, ChangePercentRank, ChangePriceRank, and DayRangeRank with a configurable limit and sort order.