Korea Tourism API MCP Server ✈️

<!-- Badges -->

Unlock the wonders of South Korean tourism directly within your AI assistant! This project provides a Model Context Protocol (MCP) server powered by the official Korea Tourism Organization (KTO) API. Equip your AI with the ability to discover vibrant festivals, serene temples, delicious restaurants, comfortable accommodations, and much more across Korea.

Links:

- PyPI Package: https://pypi.org/project/mcp-korea-tourism-api/
- GitHub Repository: https://github.com/harimkang/mcp-korea-tourism-api
- Releases: https://github.com/harimkang/mcp-korea-tourism-api/releases

✨ Features

- Comprehensive Search: Find tourist spots, cultural sites, events, food, lodging, and shopping via keywords, area, or location.
- Rich Details: Access descriptions, operating hours, admission fees, photos, addresses, and contact information.
- Location-Aware: Discover attractions near specific GPS coordinates.
- Timely Information: Find festivals and events based on date ranges.
- Multilingual Support: Get information in various languages supported by the KTO API (including English).
- Supported Languages: English, Japanese, Simplified Chinese, Traditional Chinese, Russian, Spanese, German, French
- Efficient & Resilient:
- Response Caching: Uses time-to-live (TTL) caching to store results and reduce redundant API calls, improving speed.
- Rate Limiting: Respects API usage limits to prevent errors.
- Automatic Retries: Automatically retries requests in case of temporary network or server issues.
- MCP Standard: Seamlessly integrates with AI assistants supporting the Model Context Protocol.

⚠️ Prerequisites

Before you begin, you must obtain an API key from the Korea Tourism Organization (KTO) Data Portal.

1. Visit the KTO Data Portal (or the specific portal for the tourism API if available).
2. Register and request an API key for the "TourAPI" services (you might need to look for services providing information like areaBasedList, searchKeyword, detailCommon, etc.).
3. Keep your Service Key (API Key) safe. It will be required during installation or runtime.

> You need to apply for the API below to make a request for each language.
>
> - English: https://www.data.go.kr/data/15101753/openapi.do
> - Japanese: https://www.data.go.kr/data/15101760/openapi.do
> - Simplified Chinese: https://www.data.go.kr/data/15101764/openapi.do
> - Traditional Chinese: https://www.data.go.kr/data/15101769/openapi.do
> - Russian: https://www.data.go.kr/data/15101831/openapi.do
> - Spanese: https://www.data.go.kr/data/15101811/openapi.do
> - German: https://www.data.go.kr/data/15101805/openapi.do
> - French: https://www.data.go.kr/data/15101808/openapi.do

🚀 Installation & Running

You can run this MCP server using either uv (a fast Python package installer and runner) or Docker.

Installing via Smithery

To install Korea Tourism API MCP Server for Claude Desktop automatically via Smithery:

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

Option 1: Using uv (Recommended for local development)

1. Clone the repository:

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

    cd mcp-korea-tourism-api

    

    # On macOS/Linux
    export KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
# On Windows (Command Prompt)

    # set KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"
# On Windows (PowerShell)

    # $env:KOREA_TOURISM_API_KEY="YOUR_KTO_API_KEY"

    

_Note: For persistent storage, add this line to your shell's configuration file (e.g., .zshrc, .bashrc, or use system environment variable settings)._

3. Install dependencies and run the server:
This command uses uv to install dependencies based on uv.lock (if available) or pyproject.toml and then runs the server module.

    # Install Dependency with uv
    uv sync
# Default: stdio transport (for MCP clients)

    uv run -m mcp_tourism.server
# HTTP transport for web applications

    uv run -m mcp_tourism.server --transport streamable-http --host 127.0.0.1 --port 8000
# SSE transport for real-time applications

    uv run -m mcp_tourism.server --transport sse --host 127.0.0.1 --port 8080
# Using environment variables

    export MCP_TRANSPORT=streamable-http

    export MCP_HOST=0.0.0.0

    export MCP_PORT=3000

    uv run -m mcp_tourism.server

    

The server will start and listen for MCP requests via the specified transport protocol.

Option 2: Using Docker (Recommended for isolated environment/deployment)

1. Clone the repository:

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

    cd mcp-korea-tourism-api

    

    # Default build (stdio transport)
    docker build -t mcp-korea-tourism-api .
# Build with HTTP transport configuration

    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 \

      .
# Build with SSE transport configuration

    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. Run the Docker Container:
You can run the container with different transport configurations:
- Stdio Transport (Default - for MCP clients):

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

- HTTP Transport (for web applications):

      # Using runtime environment variables
      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
# Check health: curl http://localhost:8000/health

      

- SSE Transport (for real-time applications):

      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
      

- Using Docker Compose (Recommended):

      # Copy and configure environment variables
      cp docker.env.example .env
      # Edit .env file with your API key and preferred settings
# Run with HTTP transport (default profile)

      docker-compose up mcp-tourism-http
# Run with SSE transport

      docker-compose --profile sse up mcp-tourism-sse
# Run development setup with debug logging

      docker-compose --profile dev up mcp-tourism-dev

      

🔧 Transport Configuration

The Korea Tourism API MCP Server supports multiple transport protocols to accommodate different use cases:

Available Transports

1. stdio (Default): Standard input/output transport for direct MCP client integration
- Best for: Claude Desktop, Cursor, and other MCP-compatible AI assistants
- Configuration: No additional setup required

2. streamable-http: HTTP-based transport for web applications
- Best for: Web applications, REST API integration, load balancers
- Features: HTTP endpoints, health checks, JSON responses
- Default endpoint: http://localhost:8000/mcp

3. sse: Server-Sent Events transport for real-time applications
- Best for: Real-time web applications, event-driven architectures
- Features: Real-time streaming, persistent connections
- Default endpoint: http://localhost:8080/mcp

Configuration Options

You can configure the server using command line arguments or environment variables:

| Setting | CLI Argument | Environment Variable | Default | Description |
| --------- | ------------- | -------------------- | ----------- | -------------------------------- |
| Transport | --transport | MCP_TRANSPORT | stdio | Transport protocol to use |
| Host | --host | MCP_HOST | 127.0.0.1 | Host address for HTTP transports |
| Port | --port | MCP_PORT | 8000 | Port for HTTP transports |
| Path | --path | MCP_PATH | /mcp | Path for HTTP endpoints |
| Log Level | --log-level | MCP_LOG_LEVEL | INFO | Logging level |

Command Line Examples

```bash