Skip to content

setup-docker.md

Latest commit

 

History

History
191 lines (138 loc) · 5.49 KB

setup-docker.md

File metadata and controls

191 lines (138 loc) · 5.49 KB

Run the MCP Server in Docker

This page describes how to run the real estate MCP server using Docker Compose, with Caddy as a reverse proxy.

Use this setup when you want to serve the MCP server over HTTP — for example, to connect ChatGPT or other remote clients.

Prerequisites

Run on local machine

  1. Get the repository root.

    # bash/zsh
REPOSITORY_ROOT=$(git rev-parse --show-toplevel)
    # PowerShell
$REPOSITORY_ROOT = git rev-parse --show-toplevel

  2. Create a .env file in the project root. Make sure to replace your_api_key_here with your actual key.

    cp .env.example .env
    DATA_GO_KR_API_KEY=your_api_key_here

    DATA_GO_KR_API_KEY is also used by default for Applyhome (odcloud) and Onbid. If you want different keys per service, add them to the .env file:

    ODCLOUD_API_KEY=...        # Applyhome Authorization header
ODCLOUD_SERVICE_KEY=...    # Applyhome query param
ONBID_API_KEY=...          # Onbid

  3. Build and start the containers.

    # bash/zsh
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml up -d --build
    # PowerShell
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml up -d --build

  4. Verify the MCP server is running.

    The MCP endpoint requires specific headers, so use the command below instead of a plain curl.

    curl -s -X POST http://localhost/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

    You should receive a JSON response containing protocolVersion.

  5. Connect Claude Desktop to the running server. Open claude_desktop_config.json:

    # macOS
open "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

    Add the entry below under mcpServers:

    {
  "mcpServers": {
    "real-estate": {
      "url": "http://localhost/mcp"
    }
  }
}

    Restart Claude Desktop. Setup is complete when you can see the real-estate server in the tool list.

  6. To stop the containers:

    # bash/zsh
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml down
    # PowerShell
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml down

    To also remove certificate volumes:

    # bash/zsh
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml down -v
    # PowerShell
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml down -v

Run on a home server (domain + HTTPS)

Caddy automatically obtains and renews a Let's Encrypt certificate when a domain name is configured.

  1. Point your domain to the home server's public IP address using your DNS provider or a DDNS service (e.g. No-IP).

  2. Forward ports 80 and 443 on your router to the home server.

  3. Replace :80 in docker/Caddyfile with your domain name.

    your-domain.com {
    reverse_proxy /mcp* mcp:8000
}

  4. Restart the Caddy container to apply the new configuration and obtain the certificate.

    # bash/zsh
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml restart caddy
    # PowerShell
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml restart caddy

  5. Verify the endpoint is reachable from outside.

    curl https://your-domain.com/mcp

Check logs

# bash/zsh
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml logs -f mcp
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml logs -f caddy
# PowerShell
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml logs -f mcp
docker compose -f $REPOSITORY_ROOT/docker/docker-compose.yml logs -f caddy

Services

Service Image Port Role
auth local build 9000 (internal only) OAuth token server
mcp local build 8000 (internal only) MCP HTTP server
caddy caddy:2-alpine 80, 443 Reverse proxy

The auth and mcp containers are not exposed directly on any host port. All traffic reaches them through Caddy.

Authentication

By default, AUTH_MODE=none — no authentication required, suitable for local trusted networks.

To enable OAuth for public internet access (Claude Web, ChatGPT Web), see setup-oauth.md.

Environment variables

Variable Default Description
DATA_GO_KR_API_KEY — 공공데이터포털 API key (required)
ONBID_API_KEY falls back to DATA_GO_KR_API_KEY Onbid API key
ODCLOUD_API_KEY falls back to DATA_GO_KR_API_KEY Applyhome Authorization header
ODCLOUD_SERVICE_KEY falls back to DATA_GO_KR_API_KEY Applyhome query param
FORWARDED_ALLOW_IPS 127.0.0.1 Trusted proxy IPs (set to caddy in docker-compose)
AUTH_MODE none Auth mode: oauth or none — see setup-oauth.md