MCP TWFood

An MCP (Model Context Protocol) server for twfood.cc — Taiwan's agricultural wholesale market real-time price data platform. Provides 6 AI-callable tools to search products and query daily, weekly, monthly, yearly trade data and cross-market price comparisons.

繁體中文

Features

• 6 MCP tools — Search products, query trade data at 4 time granularities, cross-market comparison
• No authentication — Uses public twfood.cc APIs, no credentials needed
• Historical data — Yearly summaries back to 1996
• 16+ wholesale markets — Cross-market volume and price comparison
• 2,000+ products — Vegetables, fruits, flowers, imported items

Prerequisites

• Python 3.10+
• No API credentials required (public data)

Installation

From PyPI

pip install mcp-twfood

Using uvx (no install)

uvx mcp-twfood

From source

git clone https://github.com/asgard-ai-platform/mcp-twfood.git
cd mcp-twfood
uv venv && source .venv/bin/activate
uv pip install -e .

Quick Start

# Test connection
python scripts/auth/test_connection.py

# Run all tool tests
python tests/test_all_tools.py

# Start MCP server
python mcp_server.py

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "twfood": {
      "command": "python",
      "args": ["/path/to/mcp-twfood/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-twfood"
      }
    }
  }
}

Claude Code

The .mcp.json file is auto-discovered when you open the project directory.

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "twfood": {
      "command": "python",
      "args": ["/path/to/mcp-twfood/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/mcp-twfood"
      }
    }
  }
}

Usage Examples

"What was last week's cabbage price?"

You: 我想知道上週高麗菜的批發價格

AI calls:

search_products(keyword="高麗菜")

Found item code LA1. Then:

get_weekly_trades(item_code="LA1", start_date="2026/03/24")

Result: SUCCESS — Last week (week 14) cabbage averaged 6.47 TWD/kg, total volume 4,041,510 kg. Price has been gradually rising from 5.76 in early March.

"Compare cabbage prices across all wholesale markets"

You: 全台各批發市場的高麗菜行情比較

AI calls:

get_market_history(item_code="LA1")

Result: SUCCESS — Returns volume and price time series for 17 markets. For example, 台北二 averages 7.2 TWD/kg while 西螺鎮 averages 5.1 TWD/kg — regional price differences clearly visible.

"Daily pineapple prices for March"

You: 三月份金鑽鳳梨每天的批發價多少？

AI calls:

get_daily_trades(item_code="B2", start_date="2026/03/01")

Result: SUCCESS — 33 daily records. March 1: avg 28.02, high 36.75, low 20.02 TWD/kg with volume 126,913 kg. Prices fluctuated between 20–37 TWD/kg range throughout the month.

"How have strawberry prices changed over the years?"

You: 草莓歷年來的價格變化？

AI calls:

get_yearly_trades(item_code="N1")

Result: SUCCESS — 31 years of data since 1996. Prices rose from ~40 TWD/kg in the early 2000s to 80–98 TWD/kg in recent years (2022: 97.8, 2023: 80.73, 2024: 81.86, 2025: 94.23 TWD/kg).

"Monthly banana market trends"

You: 香蕉近一年的月度走勢

AI calls:

get_monthly_trades(item_code="A1", start_date="2025/04/01")

Result: SUCCESS — 12 monthly summaries showing seasonal price and volume patterns. Useful for understanding supply cycles and planning purchasing.

"What pineapple varieties are available?"

You: 有哪些鳳梨品種？

AI calls:

search_products(keyword="鳳梨")

Result: SUCCESS — Found 7 varieties: 鳳梨-開英 (B1), 鳳梨-金鑽鳳梨 (B2), 鳳梨-香水鳳梨 (B3), 鳳梨-鳳梨花 (B4), 鳳梨-蜜鳳梨 (B5), 鳳梨-其他 (B9), plus 釋迦-鳳梨釋迦 (32).

"Is garlic expensive right now?"

You: 最近蒜頭貴不貴？幫我查一下

AI calls:

search_products(keyword="蒜頭")

Found 大蒜-蒜頭 with code SG5. Then:

get_daily_trades(item_code="SG5", start_date="2026/03/01")

Result: SUCCESS — Returns daily prices so you can compare current prices against recent trends and decide whether to buy now or wait.

"Which market has cheapest cabbage?"

You: 哪個批發市場的高麗菜最便宜？

AI calls:

get_market_history(item_code="LA1")

Result: SUCCESS — AI analyzes the price time series across 17 markets and identifies the markets with consistently lower prices. Southern and central markets (e.g., 西螺鎮, 溪湖鎮) tend to have lower prices than 台北二.

Tools Reference

ItemCode Reference

Use search_products to find the exact item code for any product.

Architecture

stdio (JSON-RPC 2.0)
  → mcp_server.py (entry point)
    → app.py (FastMCP singleton)
      → tools/twfood_tools.py (@mcp.tool() — 6 tools)
        → connectors/rest_client.py (HTTP GET with retry)
          → auth/none.py (no auth — public API)
            → config/settings.py (twfood.cc endpoints)

Publishing to PyPI

This project uses GitHub Actions for automated PyPI publishing.

Setup (one-time)

1. PyPI Trusted Publisher — Go to pypi.org/manage/account/publishing and add:

   • PyPI project name: mcp-twfood
   • Owner: asgard-ai-platform
   • Repository: mcp-twfood
   • Workflow name: publish.yml
   • Environment name: pypi

2. GitHub Environment — Repo Settings > Environments > New environment named pypi

Release

# Tag and create release — triggers publish workflow
gh release create v0.1.0 --title "v0.1.0 - Initial Release" --notes "Initial release with 6 tools for Taiwan agricultural wholesale market data"

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE for details.

Part of the Asgard Ecosystem

This server is part of the Asgard AI Platform open-source ecosystem, connecting AI to real-world services across e-commerce, finance, government data, IoT, social media, and more.