Thsrc MCP

🚀 MCP Server THSRC - Taiwan High - Speed Rail Information Query Service

This is a server for querying Taiwan High - Speed Rail data based on the Model Context Protocol (MCP). It provides real - time high - speed rail timetable, station information, train status, and seat query functions.

🚀 Quick Start

Method 1: Using npx (Recommended)

Use it directly without installation:

npx @physictim/mcp-server-thsrc --help

Method 2: Using pipx

# Install pipx (if not already installed)
python -m pip install --user pipx
python -m pipx ensurepath

# Install the MCP server from GitHub
pipx install git+https://github.com/physictim/thsrc_mcp.git

Method 3: Manual Installation

# Clone the project
git clone https://github.com/physictim/thsrc_mcp.git
cd thsrc_mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

✨ Features

• 🚄 Comprehensive High - Speed Rail Data Query: Timetable, real - time train schedules, and seat status.
• 🌐 Multilingual Support: Supports queries by Chinese station names, English station names, and station IDs.
• 🔄 Real - Time Data: Integrates with the TDX (Transport Data eXchange) API.
• 📱 MCP Standard: Compatible with all applications that support the MCP.

📦 Installation

Method 1: Using pipx (Recommended)

# Install pipx (if not already installed)
python -m pip install --user pipx
python -m pipx ensurepath

# Install the MCP server
pipx install git+https://github.com/yourusername/mcp-server-thsrc.git

Method 2: Using pip directly

pip install git+https://github.com/yourusername/mcp-server-thsrc.git

Method 3: Manual Installation

git clone https://github.com/yourusername/mcp-server-thsrc.git
cd mcp-server-thsrc
pip install -e .

Environment Configuration

1. Register for a TDX account: Go to TDX Transport Data eXchange Platform.
2. Obtain API keys (Client ID and Client Secret).

Start the Service

python thsrc.py

Integration with Claude Desktop

1. Obtain TDX API Keys

Go to TDX Transport Data eXchange Platform to register and obtain:

• Client ID
• Client Secret

2. Configure Claude Desktop

Find the configuration file for Claude Desktop:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

3. Edit the Configuration File

Add the following settings to claude_desktop_config.json:

If you use npx (Recommended):

{
  "mcpServers": {
    "thsrc": {
      "command": "npx",
      "args": ["-y", "@physictim/mcp-server-thsrc"],
      "env": {
        "TDX_CLIENT_ID": "Paste your Client ID here",
        "TDX_CLIENT_SECRET": "Paste your Client Secret here"
      }
    }
  }
}

If you install using pipx:

{
  "mcpServers": {
    "thsrc-mcp": {
      "command": "mcp-server-thsrc",
      "env": {
        "TDX_CLIENT_ID": "Paste your Client ID here",
        "TDX_CLIENT_SECRET": "Paste your Client Secret here"
      }
    }
  }
}

If you install manually:

{
  "mcpServers": {
    "thsrc-mcp": {
      "command": "/path/to/your/python3",
      "args": ["/path/to/your/thsrc.py"],
      "env": {
        "TDX_CLIENT_ID": "Paste your Client ID here",
        "TDX_CLIENT_SECRET": "Paste your Client Secret here"
      }
    }
  }
}

4. Restart Claude Desktop

Restart Claude Desktop, and the MCP server will be automatically loaded.

5. Verify the Connection

Enter the following in Claude Desktop:

Please help me query the list of Taiwan High - Speed Rail stations.

If the configuration is successful, Claude will use the MCP tool to query and return the high - speed rail station information.

💻 Usage Examples

After configuration, you can use natural language queries directly in Claude Desktop:

• "Query the high - speed rail schedules from Taipei to Zuoying tomorrow."
• "What schedules are available at Taichung Station now?"
• "Detailed information about Train No. 823 tomorrow."
• "Are there any available seats from Taipei to Kaohsiung?" Claude will automatically call the corresponding MCP tool to obtain real - time data.

1. Query the Station List

get_thsr_stations()

Get information about all Taiwan High - Speed Rail stations.

2. Query the Timetable

get_thsr_timetable("Taipei", "Zuoying", "2024-01-01")

Query the train timetable for a specified route and date.

Parameter Explanation:

• origin_station: Departure station (supports Chinese station names like "Taipei" or station IDs like "1000").
• destination_station: Arrival station (supports Chinese station names like "Zuoying" or station IDs like "1070").
• travel_date: Travel date (in YYYY - MM - DD format).

3. Query Real - Time Train Schedules

get_thsr_live_schedule("Taipei")

Get the real - time train status of a specified station.

Parameter Explanation:

• station: Station name or ID.

4. Query Specific Train Information

get_thsr_train_info("823", "2024-01-01")

Query detailed information about a specific train.

Parameter Explanation:

• train_no: Train number.
• travel_date: Travel date (in YYYY - MM - DD format).

5. Query Available Seats

get_thsr_available_seats("Taipei", "Zuoying", "2024-01-01")

Query the available seat status for a specified route.

Parameter Explanation:

• origin_station: Departure station.
• destination_station: Arrival station.
• travel_date: Travel date.

Update Frequency:

• Same - day queries: Updated every 10 minutes.
• Other dates: Updated at 10:00, 16:00, and 22:00 daily.

Supported Stations

Resources

thsr://stations

An MCP resource that provides station information and can be directly accessed in applications that support MCP.

💻 Usage Examples

Query schedules from Taipei to Zuoying

# Using Chinese station names
result = await get_thsr_timetable("Taipei", "Zuoying", "2024-01-01")

# Using English station names
result = await get_thsr_timetable("Taipei", "Zuoying", "2024-01-01")

# Using station IDs
result = await get_thsr_timetable("1000", "1070", "2024-01-01")

Query real - time schedules at Taipei Station

result = await get_thsr_live_schedule("Taipei")

Query seat status

result = await get_thsr_available_seats("Taipei", "Zuoying", "2024-01-01")

⚠️ Important Note

1. API Limits: Please comply with the usage limits of the TDX API.
2. Authentication: Ensure that the TDX API keys are correctly configured.
3. Date Format: Dates must be in the YYYY - MM - DD format.
4. Station Name Input: Supports both Chinese and English station names, and is case - sensitive.

Error Handling

• Invalid station name: A ValueError will be thrown.
• API authentication failure: Please check the environment variable settings.
• Network connection issues: Please confirm the network connection status.

📄 License

This project is licensed under the MIT License.

Related Links

• TDX Transport Data eXchange Platform
• Taiwan High - Speed Rail Official Website
• Model Context Protocol