tw-stock-agent

A Model Context Protocol (MCP) server for Taiwan stock data.

python

2

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "clsung-tw-stock-agent": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "mcp_server.py"
      ]
    }
  }
}

You can access Taiwan stock market data through the MCP server tw-stock-agent to query company fundamentals, price history, real-time quotes, and market overviews. This server is built to be fast, asynchronous, and ensures structured outputs suitable for programmatic consumption via MCP clients.

How to use

To use the server with an MCP client, start the local MCP server in development mode and connect your client to the provided tools. You can query stock fundamentals, price history, real-time data, market overview, and technical analysis points for Taiwan-listed and over-the-counter stocks.

How to install

Prerequisites: ensure you have Python 3.11 or higher and a compatible MCP tooling environment.

# 1. Clone the project repository
git clone https://github.com/clsung/tw-stock-agent.git
cd tw-stock-agent

# 2. Install and configure runtime tooling (uv is the required tool)
uv sync

# 3. Set up code quality and type checks (optional but recommended)
uv run pre-commit install

# 4. Prepare environment variables (if a template exists)
cp .env.example .env

Run the MCP server in development mode using the preferred FastMCP setup.

# Start the MCP server (stdio mode with local server)
uv run python mcp_server.py

# Optional: use MCP development tool (if available)
uv run mcp dev mcp_server.py

Additional content

MCP tools exposed by the server cover stock data and analysis capabilities. You can access these through your MCP client by invoking the corresponding tool names and passing the required parameters.

Key tools available include get_stock_data for fundamentals, get_price_history for historical OHLCV data, get_realtime_data for current quotes, get_best_four_points for four-point technical analysis, and get_market_overview for overall market context.

Performance characteristics include real-time data caching with a 1-minute TTL and historical data caching with a 30-minute TTL. API-like rate limits align with common stock exchange constraints to prevent overuse.

Available tools

get_stock_data

Fetches basic stock information including company overview, industry, and market capitalization.

get_price_history

Retrieves historical price data with OHLCV and volume for a given stock code and period.

get_realtime_data

Provides real-time stock information such as current price and trading volume.

get_best_four_points

Performs the four-key points technical analysis to identify potential buy/sell signals.

get_market_overview

Returns market-wide indices and general market conditions.