Orizn Visa

Orizn Visa API MCP 서버

Orizn Visa API MCP 서버는 AI 어시스턴트에게 모든 여권/목적지 조합에 대한 비자 및 입국 요건을 15개 언어로 제공하는 Model Context Protocol(MCP) 서버입니다.

데이터 범위는 지속적으로 확장됩니다. 여기에 곧 만료될 숫자를 인쇄하는 대신, get_coverage_stats 도구가 API에서 실시간으로 읽어옵니다(공개 주소: https://visa.orizn.app/api/v1/visa/stats).

"프랑스에서 일본으로 갈 때 비자가 필요한가요?", "미국 시민이 중국을 방문할 때 필요한 서류는 무엇인가요?", "인도 여권으로 이스탄불에서 환승 중 공항을 나갈 수 있나요?"와 같은 질문에 추측이 아닌 데이터로 답변합니다.

호환성

이 서버는 stdio를 통해 MCP를 지원하며 Node.js 18 이상에서 실행됩니다. Claude Desktop, Claude Code, Cursor를 포함하여 stdio 서버를 실행할 수 있는 모든 MCP 클라이언트와 호환됩니다. 아래 구성 블록은 모든 클라이언트에 동일하게 적용됩니다.

설치

npx orizn-visa-mcp

빌드하거나 클론할 것이 없습니다. MCP 클라이언트 구성에 추가하기만 하면 됩니다:

{
  "mcpServers": {
    "orizn-visa": {
      "command": "npx",
      "args": ["-y", "orizn-visa-mcp"]
    }
  }
}

클라이언트를 재시작한 후 질문해 보세요: "프랑스에서 일본으로 갈 때 비자가 필요한가요?" — API 키 없이도 작동하며, 하루 10회 확인이 가능합니다.

그 외의 모든 기능(서류, 수수료, 처리 시간, 환승 규정, 15개 언어)을 이용하려면 무료 키를 추가하세요:

{
  "mcpServers": {
    "orizn-visa": {
      "command": "npx",
      "args": ["-y", "orizn-visa-mcp"],
      "env": {
        "ORIZN_API_KEY": "orizn_visa_..."
      }
    }
  }
}

키는 인수로도 전달할 수 있으며, 환경 변수보다 우선합니다:

npx orizn-visa-mcp --api-key orizn_visa_...

예시 질문

• "프랑스에서 태국으로 여행할 때 비자가 필요한가요?"
• "미국 시민이 중국을 방문할 때 필요한 서류는 무엇인가요?"
• "브라질 여권으로 태국, 베트남, 인도네시아를 비교해 주세요."
• "중국 여권으로 이스탄불에서 12시간 환승 중 공항을 나갈 수 있나요?"
• "필리핀 여권 소지자의 솅겐 비자 비용은 얼마인가요?"
• "프랑스 여권으로 브라질에 입국할 때 필요한 예방접종은 무엇인가요?"
• "태국 비자를 3일 초과 체류하면 벌금이 얼마인가요?"
• "포르투갈에 디지털 노마드 비자가 있나요? 비용은 얼마인가요?"
• "Réponds en français : ai-je besoin d'un visa pour le Japon avec un passeport marocain ?"

도구

도구	인수	반환 내용	요금제
check_visa_requirement	passport, destination, lang	한 여권에서 한 목적지로의 전체 입국 요건: 요건 유형, 허용 일수, 서류, 신청 절차, 수수료, 처리 시간, 여권 유효기간, 사진 규격, 예방접종, 보험, 안전 경고, 초과 체류 벌금, 항공/육로/해상 입국, 원격 근무 비자, 연장 및 미성년자 규정, 대사관.	모든 키
quick_visa_check	passport, destination	한 줄: 요건 코드, 무비자 허용 일수, 마지막 검증 날짜. 서류, 수수료, 번역 없음.	없음 — 키 없이 10회/일, 모든 키로 무제한
compare_destinations	passport, destinations (1–25), lang	한 여권에 대해 최대 25개 목적지를 나란히 비교: 요건, 무비자 일수, 설명, 여권 유효기간, 수수료, 안전, 건강, 예방접종, 보험, 교통수단별 입국, 원격 근무 비자. 각 목적지 반환은 요청 1회로 계산됩니다.	Hobby 이상
check_transit_visa	passport, transit_country, lang	환승 규정만: 환승 중 공항 구역에 머물 수 있는지 또는 공항을 나갈 수 있는지, 주요 허브가 제공하는 무료 환승 시간.	Hobby 이상
get_coverage_stats	없음	데이터베이스 규모: 쌍, 여권, 목적지, 번역, 언어, 요건 유형 분포. 특정 쌍에 대한 정보는 포함하지 않습니다.	없음
get_recent_changes	passport, destination, since, limit (모두 선택 사항)	최근 변경된 비자 규정과 이를 보고한 출처 및 날짜. 피드는 현재 중단됨 — 아래 참조.	없음

국가 코드는 ISO 3166-1 alpha-3 (FRA, JPN, USA) 형식이며, alpha-2가 아닙니다.

requirement는 visa_free, visa_required, e_visa, visa_on_arrival, eta, no_admission 중 하나이며, 드물게 partial_restrictions, admission_refused, not_applicable, special도 포함됩니다.

리소스

visa://supported-languages — lang에서 허용하는 15개 코드로, 무료를 포함한 모든 요금제에서 사용 가능: en fr es pt de ja ko zh ru it ar hi th vi tl.

get_recent_changes은 의도적으로 아무것도 반환하지 않습니다

Orizn의 정책 변경 피드는 꺼져 있습니다. 내부 Orizn 테이블 두 개 사이에서 감지된 불일치를 공식 정책 변경으로 제공하고 있었기 때문에, 현재 HTTP 503을 반환하며 이 도구는 다음과 같이 동작합니다:

{ "status": "unavailable", "changes": [], "do_not_conclude": "This is NOT evidence that no visa rules changed..." }

이 도구는 의도적으로 이 상태로 제공됩니다: 비어 있고 명확하게 표시된 답변이 정직한 답변이며, 피드가 검증된 공식 출처에서 실행되는 날부터 실제 항목을 반환하기 시작합니다. 그때까지 출처와 날짜가 없는 항목은 표시되지 않고 보류됩니다.

인증 및 무료 티어

quick_visa_check, get_coverage_stats, get_recent_changes은 API 키 없이 작동합니다. 키 없는 quick_visa_check은 하루 10회 확인으로 제한됩니다 — visa.orizn.app이 익명 방문자에게 제공하는 것과 동일한 허용량입니다. 이 한도를 초과하면 도구는 조용히 실패하는 대신 이를 알리고 무료 키를 안내합니다. 한도는 실행 중인 서버 프로세스별로 적용되며 00:00 UTC에 초기화됩니다.

나머지 세 도구는 API 키가 필요하며, x-api-key 헤더로 https://visa.orizn.app/api/v1/visa에 전송됩니다.

**visa.orizn.app/visa-api**에서 무료 키를 받으세요 — 신용카드가 필요 없습니다. 무료 티어는 월 50회 요청(이메일 확인 전까지 5회)이며 핵심 필드와 15개 언어를 모두 포함합니다. 무료 요금제에서는 수수료, 처리 일수, 사진 규격, 예방접종, 보험, 환승 비자, 교통수단별 입국, 초과 체류 벌금, 원격 근무 비자, 대사관과 같은 심층 필드가 {"upgrade": "..."} 자리 표시자로 반환되며, compare_destinations과 check_transit_visa는 제한됩니다.

Hobby는 월 $9로 10,000회 요청이며 모든 기능이 잠금 해제됩니다: 업그레이드. 더 높은 볼륨 요금제는 가격 페이지에 나열되어 있습니다.

MCP 구성의 env 블록에 키를 전달하세요 — MCP 클라이언트는 셸 환경을 상속하지 않으므로 터미널에서 ORIZN_API_KEY를 내보내는 것만으로는 충분하지 않습니다.

MCP 클라이언트 없이 키를 확인하려면:

curl -H "x-api-key: $ORIZN_API_KEY" \
  "https://visa.orizn.app/api/v1/visa/check?passport=FRA&destination=JPN"

{ "passport": "FRA", "destination": "JPN", "requirement": "visa_free", "visa_free_days": 90 }

문제 해결

증상	해결 방법
"No Orizn API key"	키 전용 도구에서 예상되는 메시지입니다. quick_visa_check는 여전히 응답합니다. 해제하려면 셸이 아닌 구성 파일의 env 블록에 키를 넣고 클라이언트를 재시작하세요
"Keyless daily limit reached"	오늘의 무료 10회 확인을 모두 사용했습니다. 무료 키로 한도가 제거됩니다
HTTP 403, "check ORIZN_API_KEY for typos"	키가 잘못되었거나, 취소되었거나, 공백이 포함되어 있습니다
HTTP 403, "requires Hobby plan or above"	키는 맞지만 요금제가 다릅니다 — 이 도구는 유료입니다
HTTP 429	월별 할당량을 모두 사용했습니다
실제 국가에서 HTTP 404	alpha-3 코드(FRA, JPN)를 사용하세요. alpha-2(FR, JP)가 아닙니다
아무것도 작동하지 않음	get_coverage_stats을 호출하세요 — 키가 필요 없습니다. 그것도 실패하면 네트워크 문제입니다
get_recent_changes가 빈 목록을 반환	예상된 동작입니다 — 피드가 재구축 중입니다. 규정이 변경되지 않았다는 의미는 아닙니다

링크

• 웹사이트 — visa.orizn.app
• API 문서 — visa.orizn.app/visa-api/dashboard/docs
• 무료 키 받기 — visa.orizn.app/visa-api
• GitHub — github.com/MattJeff/orizn-mcp-server
• 지원 — api@orizn.app

라이선스

MIT