Gosar MCP 서버

Claude가 사용자를 대신하여 Gosar API를 호출할 수 있게 해주는 MCP 서버로, Gosar의 OAuth 2.0 + PKCE 흐름을 통해 인증합니다.

이 서버는 브리지 역할을 합니다:

• Claude(MCP 클라이언트)에게는 완전한 OAuth 인증 서버처럼 동작합니다 — 동적 클라이언트 등록을 처리하고 자체 단기 토큰을 발급합니다.

• Gosar에게는 사전 등록된 단일 OAuth 클라이언트(공개, PKCE 전용)로, Gosar 통합 가이드에 설명된 실제 Authorization Code + PKCE 교환을 수행합니다.

사전 요구 사항

• Python 3.11+

• Gosar 팀에 등록된 Gosar OAuth 클라이언트(통합 가이드의 "What we need from you" 참조) — client_id와 승인된 리디렉션 URI가 필요합니다.

• 실제 Gosar API를 테스트하려면 ngrok(또는 유사한 도구) — Gosar의 리디렉션 URI는 HTTPS여야 하고 정확히 일치해야 하며, Claude도 원격 MCP 서버를 연결하려면 HTTPS URL이 필요합니다.

Related MCP server: Strava MCP Server

1. 의존성 설치

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. .env 구성

프로젝트 루트의 .env에 보유한 값을 복사하세요:

# Real values from the Gosar team
GOSAR_API_BASE_URL=https://api.gosar.example
GOSAR_CLIENT_ID=your-registered-client-id
GOSAR_SCOPES=applications.read applications.write

# Your server's own public HTTPS URL (e.g. your ngrok URL). Gosar's registered
# redirect_uri must be exactly this + GOSAR_REDIRECT_PATH.
MCP_PUBLIC_BASE_URL=https://your-tunnel.ngrok-free.app
GOSAR_REDIRECT_PATH=/gosar/callback

MCP_HOST=0.0.0.0
MCP_PORT=8000

# Generate once and keep stable — see below
JWT_SIGNING_KEY=

서명 키를 생성하세요(Gosar는 시크릿이 없는 공개 클라이언트이므로 자동으로 파생될 수 없습니다 — 필수입니다):

python -c "import secrets; print(secrets.token_urlsafe(32))"

출력값을 JWT_SIGNING_KEY에 붙여넣으세요. 재시작 간에 동일하게 유지하세요. 그렇지 않으면 연결된 모든 사용자가 로그아웃됩니다.

3. 서버를 HTTPS로 노출(실제 Gosar 테스트용)

Claude와 Gosar 모두 HTTPS를 요구합니다. 별도의 터미널에서:

ngrok http 8000

https://...ngrok-free.app URL을 .env의 MCP_PUBLIC_BASE_URL에 복사하고, {MCP_PUBLIC_BASE_URL}/gosar/callback을 등록된 리디렉션 URI로 Gosar 팀에 보내세요.

4. 서버 실행

source .venv/bin/activate
python main.py

다음과 같은 출력이 보여야 합니다:

Starting MCP server 'Gosar' with transport 'http' on http://0.0.0.0:8000/mcp
Uvicorn running on http://0.0.0.0:8000

코드 변경 시 자동 리로드

python main.py는 리로드하지 않습니다 — mcp.run()은 차단되고 자체 uvicorn 프로세스를 소유하므로 파일 감시 리로더에 넘길 수 없습니다. 개발 중에는 gosar_mcp/asgi.py의 ASGI 앱을 uvicorn에서 직접 실행하세요:

uvicorn gosar_mcp.asgi:app --reload --reload-include ".env" --host 0.0.0.0 --port 8000

• --reload는 .py 파일이 변경될 때마다 작업자 프로세스를 다시 시작합니다.

• --reload-include ".env"는 .env를 편집할 때도 다시 시작합니다(uvicorn은 기본적으로 Python 파일만 감시하며, 환경 변수는 프로세스 시작 시 한 번만 읽히므로 이 플래그가 없으면 .env 편집 후 수동 재시작이 필요합니다).

• 포트를 ngrok 터널이 가리키는 포트와 일치시키세요.

5. OAuth 연결 상태 확인

서버가 실행 중인 상태에서 검색 메타데이터가 제공되는지 확인하세요:

curl -s http://127.0.0.1:8000/.well-known/oauth-authorization-server | python3 -m json.tool

scopes_supported에 applications.read/applications.write가 있고, PKCE 메서드로 S256만 있는지 확인하세요.

6. Claude에 연결

Claude의 커넥터 설정에서 다음을 가리키는 원격 MCP 서버를 추가하세요:

https://your-tunnel.ngrok-free.app/mcp

Claude는 이 서버에 대해 OAuth 클라이언트로 자체 등록하고, 사용자를 동의 화면으로 리디렉션한 다음 Gosar의 실제 Google 로그인 + 동의 화면을 거쳐 활성 연결로 여기로 돌아옵니다. Claude에게 whoami 도구를 호출하여 예상된 Gosar 계정으로 인증되었는지 확인하세요.

참고 사항

• 토큰 저장(클라이언트 등록 + 암호화된 업스트림 Gosar 토큰)은 기본적으로 OS에 적합한 암호화된 파일 저장소를 사용합니다 — 로컬 개발에 추가 설정이 필요 없습니다. 프로덕션에서 다른 백엔드를 가리키려면 gosar_mcp/auth.py를 참조하세요.

• gosar_mcp/tools.py의 /applications 엔드포인트 경로는 자리 표시자입니다 — 통합 가이드는 OAuth 계층만 지정하고 Applications REST API 형태는 지정하지 않습니다. 실제 경로/페이로드를 Gosar 팀과 확인하고 해당 파일에서 조정하세요.