Shioaji

You run a Shioaji MCP Server to access the 永豐金證券 Shioaji trading API through a standardized MCP interface. It lets you perform authentication, fetch market data, and place or manage orders in a controlled environment, with the option to enable or disable real trading as needed.

How to use

Connect your MCP client to the Shioaji MCP Server to access account information, market data, and trading operations. You can run the MCP server in read-only mode for development or testing, or enable trading to place and cancel orders. Use your client to request account info, search for contracts, fetch real-time and historical market data, and query positions and balances. Keep trading enabled only when you understand the risks and have proper permissions.

Interaction patterns you can perform include verifying connection status, retrieving contract snapshots, querying K-bars, and listing or managing your orders and positions. Ensure you have the required API credentials (API Key and Secret Key) and that you have completed any necessary service terms and API tests before enabling trading.

How to install

Prerequisites you need before starting:

• Docker installed on your machine
• A 永豐金證券帳戶 (Securities account) and API credentials (API Key and Secret Key)
• Completed service terms and API test steps Install and run the MCP server using the prebuilt Docker image or build it locally.

# Pull the latest stable image from the GitHub Container Registry
docker pull ghcr.io/musingfox/shioaji-mcp:latest

# Run MCP server in read-only mode
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_api_key \
  -e SHIOAJI_SECRET_KEY=your_secret_key \
  -e SHIOAJI_TRADING_ENABLED=false \
  ghcr.io/musingfox/shioaji-mcp:latest

# Run MCP server with trading enabled
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_api_key \
  -e SHIOAJI_SECRET_KEY=your_secret_key \
  -e SHIOAJI_TRADING_ENABLED=true \
  ghcr.io/musingfox/shioaji-mcp:latest

If you prefer to build the Docker image locally, you can also build and run it yourself.

# Build the Docker image locally
docker build -t shioaji-mcp .

# Run the locally built MCP server in read-only mode
docker run --rm -i --platform=linux/amd64 \
  -e SHIOAJI_API_KEY=your_api_key \
  -e SHIOAJI_SECRET_KEY=your_secret_key \
  -e SHIOAJI_TRADING_ENABLED=false \
  shioaji-mcp

MCP client configuration

In your MCP client, configure a connection named shioaji to point to the MCP server. The following example shows how to set up a local Docker-based MCP server with the required environment variables.

{
  "mcpServers": {
    "shioaji": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--platform=linux/amd64",
        "-e", "SHIOAJI_API_KEY=your_api_key",
        "-e", "SHIOAJI_SECRET_KEY=your_secret_key",
        "-e", "SHIOAJI_TRADING_ENABLED=false",
        "ghcr.io/musingfox/shioaji-mcp:latest"
      ]
    }
  }
}

Available tools

get_account_info

Retrieve account information and connection status.

search_contracts

Search trading contracts by keywords, exchange, or category.

get_snapshots

Fetch real-time market snapshots for specified contracts.

get_kbars

Retrieve historical K-line data for contracts.

place_order

Place buy or sell orders with specified parameters (requires permission).

cancel_order

Cancel existing orders by order ID (requires permission).

list_orders

List all orders and their statuses.

get_positions

Get current positions and P&L for stocks, futures, or entire account.

get_account_balance

Get account balance and margin information for stocks, futures, or all accounts.

check_terms_status

Check service terms signing status and API test completion.

run_api_test

Execute API tests to verify terms compliance and login/order tests.