mcp-server-shioaji

MCP Server for Shioaji

A Model Context Protocol (MCP) server that provides AI assistants with access to Shioaji trading API for the Taiwanese financial market.

Overview

This server implements the MCP protocol to expose Shioaji API functionality as tools that can be used by AI assistants. It allows AI models to:

Retrieve current stock prices
Fetch historical data
List available stocks
And more...

Installation

Prerequisites

Python 3.10 or higher
uv (fast Python package manager)

Using uv

uv sync

Configuration

Before running the server, you need to configure your Shioaji API credentials. There are two ways to do this:

Environment Variables

Set the following environment variables:

export SHIOAJI_API_KEY="your_api_key"
export SHIOAJI_SECRET_KEY="your_secret_key"

Using .env File

Create a .env file in the root directory with the following content:

SHIOAJI_API_KEY=your_api_key
SHIOAJI_SECRET_KEY=your_secret_key

Running the Server

Start the server with:

uv run mcp-server-shioaji

The server will start on http://0.0.0.0:8000 by default.

Available Tools

The server exposes the following tools via MCP:

get_stock_price

Get the current price of a stock by its symbol.

{
  "tool": "get_stock_price",
  "params": {
    "symbols": "TW.2330,TW.2317"
  }
}

Response will include price information for the requested stocks, including open, high, low, close prices, volume, and other trading data.

get_kbars

Fetch K-Bar (candlestick) data for a stock within a date range.

{
  "tool": "get_kbars",
  "params": {
    "symbol": "TW.2330",
    "start_date": "2023-12-01",
    "end_date": "2023-12-15"
  }
}

If start_date is not provided, it defaults to today. If end_date is not provided, it defaults to the same as start_date.

scan_stocks

Scan stocks based on various ranking criteria.

{
  "tool": "scan_stocks",
  "params": {
    "scanner_type": "VolumeRank",
    "ascending": false,
    "limit": 10
  }
}

Supported scanner types:

VolumeRank - Ranking by trading volume
AmountRank - Ranking by trading amount
TickCountRank - Ranking by number of transactions
ChangePercentRank - Ranking by percentage change
ChangePriceRank - Ranking by price change
DayRangeRank - Ranking by daily range

Default limit is 20, and results are sorted in descending order by default (set ascending to true for ascending order).

Development

Project Structure

mcp-server-shioaji/
├── src/
│   └── mcp_server_shioaji/
│       ├── __init__.py      # Package entry point
│       └── server.py        # MCP server implementation
├── pyproject.toml           # Project metadata and dependencies
└── README.md                # This file

Adding New Tools

To add new Shioaji functionality, modify server.py and add new tool definitions using the @mcp.tool decorator.

License

MIT

Acknowledgements

Shioaji - The Python wrapper for SinoPac's trading API
MCP - Model Context Protocol

This server cannot be installed

security - not tested

license - not found

quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.