SVV-MCP-unofficial

⚠️ 비공식 프로젝트. 이는 커뮤니티가 만든 MCP 서버이며, Statens vegvesen(SVV)이 만들었거나 운영하거나 어떤 식으로든 관련되어 있지 않습니다. 이름의 "SVV"는 서버가 사용하는 데이터 소스가 무엇인지 설명할 뿐입니다. 전달되는 데이터는 Statens vegvesen 자체의 공개 DATEX II 엔드포인트에서 가져오며, 사용은 해당 이용 약관의 적용을 받습니다(라이선스 참조).

LLM에게 Statens vegvesen의 공개 실시간 데이터에 대한 접근을 제공하는 MCP 서버 (Model Context Protocol)입니다. DATEX II를 통해:

• 🌡️ 기상 측정 — 도로청 기상 관측소의 데이터(노면 온도, 기온, 풍속, 이슬점), 미끄러운 도로 자동 경고 포함

• 🌦️ 기상 예보 (시간별, 24시간 전망)

• 📷 웹 카메라 — 도로망을 따라

• 🚗 실시간 통행 시간 — 주요 구간

• ⚠️ 교통 정보 (사고, 도로 공사, 통제, 산사태/홍수 등)

• 🔧 내장된 문제 해결 도구로 원시 XML 구조를 표시합니다. NPRA의 스키마가 변경될 수 있기 때문입니다.

모든 DATEX 엔드포인트는 Statens vegvesen에 등록된 사용자가 필요합니다(무료). 여기에서 액세스를 요청하세요 →

목차

• 로컬에서 시작하기

• GitHub 리포지토리 설정

• 로그인 모드: 공유 계정 vs. 사용자별

• Railway에 배포

• 서버에 연결

  • Claude.ai / Claude 앱 (사용자 지정 커넥터)

  • Claude Desktop (stdio, 로컬)

  • 기타 MCP 클라이언트

• 사용 가능한 도구

• 문제 해결

Related MCP server: aria-mcp-trafik-dk

로컬에서 시작하기

Python 3.10+ 필요.

git clone https://github.com/<ditt-brukernavn>/svv-mcp-unofficial.git
cd svv-mcp-unofficial
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
# rediger .env og fyll inn DATEX_USERNAME / DATEX_PASSWORD

export $(grep -v '^#' .env | xargs)   # eller bruk python-dotenv
python server.py

환경에 PORT가 설정되어 있지 않으면 서버는 stdio로 시작됩니다. MCP Inspector로 로컬 테스트하기에 편리합니다:

npx @modelcontextprotocol/inspector python server.py

GitHub 리포지토리 설정

1. GitHub에 새(빈) 리포지토리를 만듭니다(예: svv-mcp-unofficial).

2. 코드를 푸시합니다:

   cd svv-mcp-unofficial
   git init
   git add .
   git commit -m "Initial commit: svv-mcp-unofficial server"
   git branch -M main
   git remote add origin https://github.com/<ditt-brukernavn>/svv-mcp-unofficial.git
   git push -u origin main

3. 중요: .env는 이미 .gitignore에 있습니다. 실제 DATEX 사용자 이름/비밀번호를 커밋하지 않도록 다시 확인하세요. 대신 값이 없는 .env.example을 추가하세요. 이미 리포지토리에 있습니다.

로그인 모드: 공유 계정 vs. 사용자별

서버는 SVV_MCP_PUBLIC_URL 설정 여부에 따라 두 가지 모드를 지원합니다:

다중 사용자 모드를 사용하면 다른 사람들이 자체 서버 없이 하나의 Railway URL을 공유할 수 있습니다. 누군가 Claude에 커넥터를 추가하면 서버가 자체 호스팅하는 로그인 페이지(/login)로 이동하여 자신의 DATEX 사용자 이름/비밀번호를 붙여넣고 이를 얻는 방법에 대한 링크를 확인합니다. 자격 증명은 Railway 볼륨의 SQLite 파일에 Fernet으로 암호화되어 저장되며, MCP 서버가 Claude에 발급하는 토큰에 연결됩니다.

Railway에서 다중 사용자 모드 설정

1. 서비스에 볼륨을 추가하고 /data에 마운트합니다(Railway 대시보드: Settings → Volumes → New Volume, 마운트 경로 /data).

2. 암호화 키를 생성합니다:

   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

3. 서비스에 변수를 설정합니다:

   • SVV_MCP_PUBLIC_URL = 귀하의 Railway URL(예: https://svv-mcp-unofficial-production.up.railway.app)

   • CREDENTIAL_ENCRYPTION_KEY = 2단계의 키

   • SVV_MCP_DB_PATH = /data/svv_mcp.db

   • 이 모드에서는 DATEX_USERNAME/DATEX_PASSWORD를 설정하지 마십시오

4. 다시 배포합니다. 이제 /mcp는 OAuth를 요구하며, /login은 자체 호스팅 로그인 페이지입니다.

URL을 공유하기 전에 OAuth 흐름 테스트

이것은 프로젝트에서 가장 복잡한 부분이며 한 번은 수동으로 테스트해야 합니다:

npx @modelcontextprotocol/inspector

Inspector를 https://<ditt-domene>/mcp로 지정하고 인증을 선택한 후 전체 흐름을 진행합니다(/login으로 전송되고, 테스트 값을 입력하고, 다시 전송되며, 도구 호출이 작동합니다). 문제가 발생하면 Railway 로그를 확인하세요. auth.py의 인증 서버 코드는 SDK의 OAuthAuthorizationServerProvider 인터페이스를 사용하는데, SDK 버전 간에 필드 이름이 다를 수 있습니다. 로그는 정확히 어떤 메서드/필드가 일치하지 않는지 보여줍니다.

Railway에 배포

방법 A — Railway 대시보드 이용 (가장 간단함):

1. railway.app에 로그인 → New Project → Deploy from GitHub repo.

2. svv-mcp-unofficial 리포지토리를 선택합니다. Railway가 Dockerfile을 자동으로 찾습니다.

3. 서비스의 Variables로 이동하여 원하는 모드에 대한 변수를 입력합니다 (위 표 참조).

4. Railway가 PORT를 자동으로 설정합니다. 그러면 서버는 Streamable HTTP 모드로 시작되어 0.0.0.0:$PORT에서 수신 대기합니다.

5. Settings → Networking에서 Generate Domain을 눌러 공개 URL을 얻습니다 (예: https://svv-mcp-unofficial-production.up.railway.app).

6. 그러면 MCP 엔드포인트는 https://<ditt-domene>/mcp가 됩니다.

방법 B — Railway CLI 사용:

npm i -g @railway/cli
railway login
railway init
railway up
railway variables --set "DATEX_USERNAME=..." --set "DATEX_PASSWORD=..."
railway domain

서버는 Streamable HTTP(SSE 아님)를 사용합니다. 이는 현재 사양에서 외부 MCP 서버에 권장되는 전송 방식입니다.

서버에 연결

Claude.ai / Claude 앱 (사용자 지정 커넥터)

1. Settings → Connectors → Add custom connector로 이동합니다.

2. Railway URL을 붙여넣습니다(예: https://<ditt-domene>/mcp).

3. 이름을 지정합니다(예: "Statens vegvesen").

4. 대화에서 도구/커넥터 아래에서 활성화합니다.

공유 계정 모드: 추가 단계 없음 — DATEX_USERNAME/DATEX_PASSWORD는 서버에 있으며 대화에 있지 않습니다.

다중 사용자 모드: Claude는 처음 연결할 때 서버의 /login 페이지로 자동 안내합니다. 거기에 자신의 DATEX 사용자 이름/비밀번호를 입력합니다(페이지에는 아직 없는 경우 이를 얻는 방법과 DATEX 액세스가 실제로 제공하는 도구도 표시됩니다). DATEX 액세스를 얻고 싶지 않다면 "계정 없이 계속"을 선택할 수 있습니다. 그러면 hent_apen_vegdata(NVDB, 로그인 불필요)만 사용할 수 있습니다.

Claude Desktop (stdio, 로컬)

claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "vegvesen": {
      "command": "python",
      "args": ["/full/path/til/svv-mcp-unofficial/server.py"],
      "env": {
        "DATEX_USERNAME": "...",
        "DATEX_PASSWORD": "..."
      }
    }
  }
}

(다중 사용자 모드는 HTTP가 필요하며 stdio에서는 작동하지 않습니다.)

기타 MCP 클라이언트

Streamable HTTP를 지원하는 모든 클라이언트는 https://<ditt-domene>/mcp를 직접 가리킬 수 있습니다.

사용 가능한 도구

모든 "hent" 도구는 동일한 매개변수를 사용합니다:

• sokeord (선택 사항) — 모든 필드 값을 기준으로 필터링합니다(예: "E18", "Hemsedal")

• maks_antall (기본값 10) — 응답의 최대 레코드 수

• format — "markdown"(읽기 쉬움) 또는 "json"(구조화됨)

문제 해결

• "401 인증되지 않음" → DATEX_USERNAME/DATEX_PASSWORD가 서버에 없거나 잘못되었습니다(공유 계정 모드). 또는 사용자가 로그인하려면 다시 연결해야 합니다(다중 사용자 모드).

• 빈/예상치 못한 결과 → 해당 게시물에 대해 inspiser_datex_publikasjon을 실행하여(위 server.py의 DATEX_ENDPOINTS 키 표 참조) NPRA가 현재 정확히 어떤 XML 태그를 보내는지 확인하고, 필요에 따라 해당 도구의 candidate_tags를 조정합니다.

• 시간 초과 → NPRA의 DATEX 노드가 일시적으로 다운되었을 수 있습니다. 잠시 후 다시 시도하거나 vegvesen.no의 운영 공지를 확인하세요.

• 연결 시 OAuth 오류(다중 사용자 모드) → Railway 로그와 위의 "OAuth 흐름 테스트" 섹션을 참조하세요.

라이선스

데이터는 노르웨이 공공 데이터 라이선스 (NLOD)에 따라 제공됩니다. NPRA가 요청하는 대로 데이터를 사용할 때 Statens vegvesen을 출처로 표시하십시오.