Korea Tourism API MCP Server

Korea Tourism API MCP Server ✈️

韓国観光の魅力を、AI アシスタントから直接発見しましょう！このプロジェクトは、韓国観光公社（KTO）の公式 API を利用する Model Context Protocol（MCP）サーバーを提供します。韓国各地の活気あふれるフェスティバル、静かな寺院、おいしいレストラン、快適な宿泊施設などを見つける機能を AI に加えます。

リンク：

• PyPI パッケージ： https://pypi.org/project/mcp-korea-tourism-api/
• GitHub リポジトリ： https://github.com/harimkang/mcp-korea-tourism-api
• リリース： https://github.com/harimkang/mcp-korea-tourism-api/releases

✨ 特長

• 総合検索： キーワード、地域、場所から観光スポット、文化施設、イベント、飲食店、宿泊施設、ショッピング情報を検索できます。
• 詳細情報： 説明、営業時間、入場料、写真、住所、連絡先にアクセスできます。
• 位置情報対応： 特定の GPS 座標の近くにある観光スポットを見つけられます。
• 最新情報： 日付の範囲を指定してフェスティバルやイベントを検索できます。
• 多言語対応： KTO API がサポートするさまざまな言語（英語を含む）で情報を取得できます。
  • 対応言語：英語、日本語、簡体字中国語、繁体字中国語、ロシア語、スペイン語、ドイツ語、フランス語
• 効率性と堅牢性：
  • レスポンスキャッシュ： 有効期限（TTL）付きキャッシュで結果を保存し、重複した API 呼び出しを減らして速度を向上させます。
  • レート制限： エラーを防ぐため、API の利用制限を遵守します。
  • 自動再試行： 一時的なネットワークやサーバーの問題が発生した場合、リクエストを自動的に再試行します。
• MCP 標準： Model Context Protocol に対応する AI アシスタントとシームレスに連携します。

⚠️ 前提条件

開始する前に、韓国観光公社（KTO）データポータルから API キーを取得する必要があります。

1. KTO データポータル（または、利用可能であれば観光 API 専用のポータル）にアクセスします。
2. 「TourAPI」サービスの API キーを登録して申請します（areaBasedList、searchKeyword、detailCommon などの情報を提供するサービスを探す必要がある場合があります）。
3. **サービスキー（API キー）**を安全に保管してください。インストール時または実行時に必要になります。

言語ごとにリクエストを行うには、以下の API を申請する必要があります。

• 英語：https://www.data.go.kr/data/15101753/openapi.do
• 日本語：https://www.data.go.kr/data/15101760/openapi.do
• 簡体字中国語：https://www.data.go.kr/data/15101764/openapi.do
• 繁体字中国語：https://www.data.go.kr/data/15101769/openapi.do
• ロシア語：https://www.data.go.kr/data/15101831/openapi.do
• スペイン語：https://www.data.go.kr/data/15101811/openapi.do
• ドイツ語：https://www.data.go.kr/data/15101805/openapi.do
• フランス語：https://www.data.go.kr/data/15101808/openapi.do

🚀 インストールと実行

この MCP サーバーは、uv（高速な Python パッケージインストーラー兼ランナー）または Docker を使って実行できます。

Smithery 経由でのインストール

Smithery 経由で、Claude Desktop 用の Korea Tourism API MCP Server を自動的にインストールするには：

npx -y @smithery/cli install @harimkang/mcp-korea-tourism-api --client claude

オプション 1：uv を使用する（ローカル開発におすすめ）

1. リポジトリをクローンします：

   git clone https://github.com/harimkang/mcp-korea-tourism-api.git
   cd mcp-korea-tourism-api
   

2. API キーの環境変数を設定します： "YOUR_KTO_API_KEY" を取得した実際のキーに置き換えてください。

   # macOS/Linux の場合
   export KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
   
   # Windows（コマンドプロンプト）の場合
   # set KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
   
   # Windows（PowerShell）の場合
   # $env:KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
   

   注：設定を永続化するには、この行をシェルの設定ファイル（例：.zshrc、.bashrc）に追加するか、システムの環境変数設定を使用してください。

3. 依存関係をインストールしてサーバーを実行します： このコマンドは、uv を使用して、uv.lock（利用可能な場合）または pyproject.toml に基づいて依存関係をインストールし、サーバーモジュールを実行します。

   # uv で依存関係をインストール
   uv sync
   
   # デフォルト：stdio トランスポート（MCP クライアント向け）
   uv run -m mcp_tourism.server
   
   # Web アプリケーション向けの HTTP トランスポート
   uv run -m mcp_tourism.server --transport streamable-http --host 127.0.0.1 --port 8000
   
   # リアルタイムアプリケーション向けの SSE トランスポート
   uv run -m mcp_tourism.server --transport sse --host 127.0.0.1 --port 8080
   
   # 環境変数を使用
   export MCP_TRANSPORT=streamable-http
   export MCP_HOST=0.0.0.0
   export MCP_PORT=3000
   uv run -m mcp_tourism.server
   

   サーバーが起動し、指定したトランスポートプロトコルを介して MCP リクエストを待ち受けます。

オプション 2：Docker を使用する（分離された環境での使用／デプロイに推奨）

1. リポジトリをクローンします：

   git clone https://github.com/harimkang/mcp-korea-tourism-api.git
   cd mcp-korea-tourism-api
   

2. Docker イメージをビルドします： さまざまなトランスポート設定でイメージをビルドできます。

   # デフォルトのビルド（stdio トランスポート）
   docker build -t mcp-korea-tourism-api .
   
   # HTTP トランスポート設定でビルド
   docker build -t mcp-korea-tourism-api \
     --build-arg MCP_TRANSPORT=streamable-http \
     --build-arg MCP_HOST=0.0.0.0 \
     --build-arg MCP_PORT=8000 \
     --build-arg MCP_PATH=/mcp \
     --build-arg MCP_LOG_LEVEL=INFO \
     .
   
   # SSE トランスポート設定でビルド
   docker build -t mcp-korea-tourism-api \
     --build-arg MCP_TRANSPORT=sse \
     --build-arg MCP_HOST=0.0.0.0 \
     --build-arg MCP_PORT=8080 \
     .
   

3. Docker コンテナを実行します： さまざまなトランスポート設定でコンテナを実行できます。

   • Stdio トランスポート（デフォルト — MCP クライアント向け）：

     docker run --rm -it \
       -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" \
       mcp-korea-tourism-api
     

   • HTTP トランスポート（Web アプリケーション向け）：

     # 実行時の環境変数を使用
     docker run --rm -p 8000:8000 \
       -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" \
       -e MCP_TRANSPORT=streamable-http \
       -e MCP_HOST=0.0.0.0 \
       -e MCP_PORT=8000 \
       mcp-korea-tourism-api
     
     # ヘルス状態を確認：curl http://localhost:8000/health
     

   • SSE トランスポート（リアルタイムアプリケーション向け）：

     docker run --rm -p 8080:8080 \
       -e KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY" \
       -e MCP_TRANSPORT=sse \
       -e MCP_HOST=0.0.0.0 \
       -e MCP_PORT=8080 \
       mcp-korea-tourism-api
     

   • Docker Compose を使用する場合（推奨）：

     # 環境変数をコピーして設定
     cp docker.env.example .env
     # API キーと任意の設定を .env ファイルに記述
     
     # HTTP トランスポートで実行（デフォルトのプロファイル）
     docker-compose up mcp-tourism-http
     
     # SSE トランスポートで実行
     docker-compose --profile sse up mcp-tourism-sse
     
     # デバッグログを有効にして開発環境を実行
     docker-compose --profile dev up mcp-tourism-dev
     

🔧 トランスポートの設定

Korea Tourism API MCP サーバーは、さまざまな用途に対応するため、複数のトランスポートプロトコルをサポートしています。

利用可能なトランスポート

1. stdio（デフォルト）：MCP クライアントと直接連携するための標準入力／出力トランスポート

   • 最適な用途：Claude Desktop、Cursor、その他の MCP 対応 AI アシスタント
   • 設定：追加のセットアップは不要です

2. streamable-http：Web アプリケーション向けの HTTP ベースのトランスポート

   • 最適な用途：Web アプリケーション、REST API 連携、ロードバランサー
   • 機能：HTTP エンドポイント、ヘルスチェック、JSON レスポンス
   • デフォルトのエンドポイント：http://localhost:8000/mcp

3. sse：リアルタイムアプリケーション向けのサーバー送信イベント（SSE）トランスポート

   • 最適な用途：リアルタイム Web アプリケーション、イベント駆動型アーキテクチャ
   • 機能：リアルタイムストリーミング、永続的な接続
   • デフォルトのエンドポイント：http://localhost:8080/mcp

設定オプション

コマンドライン引数または環境変数を使用してサーバーを設定できます。

設定	CLI 引数	環境変数	デフォルト	説明
トランスポート	--transport	MCP_TRANSPORT	stdio	使用するトランスポートプロトコル
ホスト	--host	MCP_HOST	127.0.0.1	HTTP トランスポート用のホストアドレス
ポート	--port	MCP_PORT	8000	HTTP トランスポート用のポート
パス	--path	MCP_PATH	/mcp	HTTP エンドポイント用のパス
ログレベル	--log-level	MCP_LOG_LEVEL	INFO	ログレベル

コマンドラインの例

# Get help for all available options
python -m mcp_tourism.server --help

# Run with HTTP transport on custom port
python -m mcp_tourism.server --transport streamable-http --port 3000 --log-level DEBUG

# Run with SSE transport
python -m mcp_tourism.server --transport sse --host 0.0.0.0 --port 8080

環境変数の例

# Set environment variables
export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
export MCP_LOG_LEVEL=INFO
export KOREA_TOURISM_API_KEY="your_api_key_here"

# Run the server
python -m mcp_tourism.server

ヘルスチェック

HTTP および SSE トランスポートでは、/health でヘルスチェックエンドポイントを利用できます。

# Check server health
curl http://localhost:8000/health

# Example response
{
  "status": "healthy",
  "service": "Korea Tourism API MCP Server",
  "transport": "streamable-http",
  "timestamp": 1640995200.0
}

🛠️ Cursor との連携

Cursor 内でこの MCP サーバーを使用するには、次の手順に従ってください。

1. Docker コンテナを実行できることを確認します： 上記の Docker インストール手順に従って、イメージ（mcp-korea-tourism-api）をビルドします。コンテナを手動で実行する必要はありません。Cursor が実行します。

2. mcp.json ファイルを見つけます： このファイルは Cursor 用の MCP ツールを設定します。通常は Cursor の設定から確認できます。または、~/.cursor/mcp.json などのパスにある場合があります。

3. MCP 設定を追加または更新します： 次の JSON オブジェクトを mcp.json ファイル内のリストに追加します。このツールのエントリがすでにある場合は、その command を更新します。"YOUR_KTO_API_KEY" を実際のキーに置き換えてください。

   {
     "mcpServers": {
       "korea-tourism": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "-e",
           "KOREA_TOURISM_API_KEY=YOUR_KTO_API_KEY",
           "mcp-korea-tourism-api"
         ]
       }
     }
   }
   

   または uv を使用します［ローカルディレクトリ］

   {
     "mcpServers": {
       "korea-tourism": {
         "command": "uv",
         "args": [
           "--directory",
           "{LOCAL_PATH}/mcp-korea-tourism-api",
           "run",
           "-m",
           "mcp_tourism.server"
         ],
         "env": {
           "KOREA_TOURISM_API_KEY": "YOUR_KTO_API_KEY"
         }
       }
     }
   }
   

4. mcp.json を保存します。

5. Cursor を再起動するか、MCP ツールを再読み込みします： Cursor がツールを検出し、必要に応じて Docker を使用して実行できるようになります。

🛠️ 提供される MCP ツール

このサーバーは、AI アシスタント向けに以下のツールを公開しています。

1. search_tourism_by_keyword：キーワード（例：「Gyeongbokgung」「Bibimbap」）を使って観光情報を検索します。コンテンツの種類、エリアコードで絞り込めます。
2. get_tourism_by_area：地域コード（例：ソウル＝「1」）を使って観光情報を閲覧します。コンテンツの種類、地区コードで絞り込めます。
3. find_nearby_attractions：指定した GPS 座標（経度、緯度）の近くにある観光スポットを検索します。検索範囲とコンテンツの種類で絞り込めます。
4. search_festivals_by_date：指定した期間（YYYYMMDD）に開催されるフェスティバルを検索します。エリアコードで絞り込めます。
5. find_accommodations：ホテル、ゲストハウスなどを検索します。エリアコードと地区コードで絞り込めます。
6. get_detailed_information：コンテンツ ID を使って、特定の項目の詳細情報（概要、利用時間、駐車場など）を取得します。コンテンツの種類で絞り込めます。
7. get_tourism_images：コンテンツ ID を使って、特定の観光項目に関連付けられた画像 URL を取得します。
8. get_area_codes：エリアコード（市・道）と、任意でサブエリア（地区）コードを取得します。

⚙️ 必要条件（uv を使用する場合）

• Python 3.12+
• uv をインストール済み（pip install uv）

使用例

この MCP と統合された AI アシスタントは、次のような問い合わせに対応できます。

• 「明洞駅の近くにあるレストランを探してください。」
• 「仏国寺の写真を見せてください。」
• 「来月、釜山で開催されるフェスティバルはありますか？」
• 「景福宮について詳しく教えてください。コンテンツ ID は 264337 です。」