Twfood

PyPI version Python License: MIT MCP GitHub stars GitHub issues GitHub last commit

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

Tool	Description	Parameters
search_products	Search 2,000+ products by name or code	keyword
get_daily_trades	Daily trade data (volume, avg/high/low price)	item_code, start_date
get_weekly_trades	Weekly trade summaries	item_code, start_date
get_monthly_trades	Monthly trade summaries	item_code, start_date
get_yearly_trades	Yearly trade summaries (back to 1996)	item_code
get_market_history	Cross-market volume & price comparison (~17 markets)	item_code

ItemCode Reference

Category	Prefix	Example
Leafy vegetables	LA	LA1 (Cabbage/高麗菜)
Legumes	FB	FB1
Seasonings	SA	SA3
Vegetable fruits	FJ	FJ3
Stem vegetables	SB	SB2
Fruits	Various	A1 (Banana), B2 (Pineapple), P1 (Guava), N1 (Strawberry)
Roses	FR	FR102
Imported roses	IR	IR101

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.

Data Source & Acknowledgements

This MCP server retrieves data from twfood.cc (當季好蔬果), a Taiwan agricultural wholesale market real-time price data platform that combines big data and data visualization technologies.

• Website: https://www.twfood.cc/
• Data license: Price-related charts are licensed under Creative Commons BY-NC-ND 4.0 International
• Data source: Taiwan wholesale market transaction records (vegetables, fruits, flowers)

We sincerely thank the twfood.cc team for making this valuable agricultural market data publicly accessible. Their work enables transparency in Taiwan's agricultural wholesale market and benefits farmers, traders, researchers, and consumers.

Note: This project is an independent open-source MCP server and is not officially affiliated with or endorsed by twfood.cc. Please respect the data license terms when using the data retrieved through this server.

License

MIT License — see LICENSE for details.

The MIT license applies to the source code of this MCP server only. The agricultural market data accessed through twfood.cc is subject to its own CC BY-NC-ND 4.0 license terms.

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.