Gologin MCP Server

AI 에이전트용 GoLogin MCP 서버

AI 대화를 통해 GoLogin 브라우저 프로필, 프록시, 핑거프린트, 폴더 및 클라우드 브라우저 세션을 관리하세요. 이 Model Context Protocol(MCP) 서버는 AI 클라이언트를 GoLogin API에 연결합니다.

빠른 시작

Node.js 22 이상, 활성 GoLogin 계정 및 GoLogin API 토큰이 필요합니다. Node.js 22 및 24 LTS는 macOS Apple Silicon에서 테스트되었습니다.

1. GoLogin 계정에 로그인하고 API & MCP를 연 다음 API 탭에서 토큰을 생성하세요.
2. MCP 클라이언트에 이 구성을 추가하고 토큰 자리 표시자를 교체하세요. 기존 mcpServers 구성에 병합하세요.

{
  "mcpServers": {
    "gologin-mcp": {
      "command": "npx",
      "args": ["-y", "gologin-mcp"],
      "env": {
        "API_TOKEN": "your-gologin-api-token-here"
      }
    }
  }
}

3. 클라이언트의 MCP 연결을 다시 시작하거나 새로 고친 다음 **"내 GoLogin 프로필을 보여줘."**라고 요청하세요.

클라이언트가 서버를 자동으로 시작합니다. -y는 npm이 대화형 확인 없이 패키지를 설치할 수 있게 합니다. 이 서버는 API_TOKEN을 읽습니다. 다른 GoLogin CLI에서 사용하는 GOLOGIN_TOKEN 변수는 여기서 별칭이 아닙니다.

터미널 시작 확인을 위해 환경에 API_TOKEN가 이미 설정된 경우:

npx -y gologin-mcp

서버는 표준 입력/출력(stdio)을 통해 통신하며 MCP 클라이언트를 기다립니다. 자체적으로 브라우저를 열거나 대화형 명령 프롬프트를 제공하지 않습니다.

할 수 있는 작업

• 브라우저 프로필 생성, 읽기, 업데이트, 삭제 및 구성.
• 프로필 프록시 구성 및 브라우저 핑거프린트 새로 고침.
• 폴더 및 해당 프로필 멤버십 관리.
• 계정 정보 읽기.
• GoLogin 클라우드에서 브라우저 프로필 시작 및 중지.

클라우드 시작은 연결 URL을 반환합니다. 이 서버는 페이지 탐색, 클릭, 양식 작성 또는 로컬 Orbita 실행 도구를 노출하지 않습니다. 페이지 자동화에는 별도의 브라우저 자동화 클라이언트 또는 GoLogin Agent Browser CLI를 사용하세요.

MCP 프로세스는 로컬에서 실행됩니다. GoLogin API 요청 및 클라우드 브라우저 세션에는 네트워크 액세스가 필요합니다. 클라우드 가용성 및 API 작업은 계정 권한과 요금제에 따라 달라집니다.

도구

도구 이름은 서버가 시작 시 로드하는 GoLogin OpenAPI 사양의 HTTP 메서드와 경로에서 생성됩니다. 다음은 사용 가능한 도구의 일부이며 고정된 별칭 목록이 아닙니다. 현재 이름과 입력 스키마는 MCP 클라이언트에서 tools/list을 쿼리하세요.

도구	설명
get_profile_v2	페이지네이션 및 폴더 필터로 프로필 나열 및 검색
post_profile_custom	이름, OS, 프록시 등 부분 설정으로 프로필 생성
get_profile_id	ID로 프로필 읽기
put_profile_id_custom	선택한 프로필 설정 업데이트
delete_profile	profilesToDelete에 나열된 프로필 삭제
patch_profile_proxy_many_v2	하나 이상의 프로필에 대한 프록시 구성
patch_profile_fingerprints	browsersIds에 나열된 프로필의 핑거프린트 새로 고침
get_proxy_v2	프록시 나열
get_folders	폴더 나열
post_folders_folder	이름으로 폴더 생성
patch_folders_folder	폴더에서 프로필 추가 또는 제거
delete_folders_folder	이름으로 폴더 삭제
post_profile_id_web	클라우드에서 프로필을 시작하고 연결 URL 반환
delete_profile_id_web	클라우드 프로필 중지
get_user	계정 정보 읽기

예를 들어 MCP 클라이언트는 프로필을 읽기 위해 이 tools/call 요청을 보낼 수 있습니다:

{
  "name": "get_profile_id",
  "arguments": {
    "id": "your-profile-id"
  }
}

인수는 각 도구의 입력 스키마를 따릅니다. 경로 및 쿼리 매개변수와 요청 본문 필드는 최상위 인수로 전달됩니다.

예시 프롬프트

• "내 GoLogin 프로필을 보여줘."
• "'Research'라는 Linux 프로필을 만들어."
• "프로필 PROFILE_ID를 'Research US'로 이름을 바꿔."
• "프로필 PROFILE_ID를 이 프록시 설정으로 업데이트해."
• "프로필 PROFILE_ID의 핑거프린트를 새로 고쳐."
• "'Research'라는 폴더를 만들고 프로필 PROFILE_ID를 추가해."
• "클라우드에서 프로필 PROFILE_ID를 시작하고 연결 URL을 알려줘."
• "프로필 PROFILE_ID의 클라우드 세션을 중지해."
• "내 GoLogin 계정 정보를 보여줘."

MCP 클라이언트 설정

Claude Desktop

Settings > Developer > Edit Config를 열고 빠른 시작 구성을 claude_desktop_config.json에 추가하세요. Claude Desktop을 완전히 종료하고 다시 시작한 다음 gologin-mcp 및 해당 도구를 사용할 수 있는지 확인하세요.

구성 경로 및 문제 해결은 공식 로컬 MCP 설정 가이드를 참조하세요.

Cursor

사용자 계정의 ~/.cursor/mcp.json 또는 프로젝트의 .cursor/mcp.json에 빠른 시작 구성을 추가하세요. MCP 연결을 새로 고치고 서버 도구를 활성화하세요. API 토큰이 포함된 구성은 버전 관리에서 제외하세요.

현재 클라이언트 설정은 Cursor의 MCP 문서를 참조하세요.

기타 MCP 클라이언트

로컬 stdio MCP 서버를 지원하는 클라이언트를 사용하세요. npx를 명령으로, -y 및 gologin-mcp을 인수로, API_TOKEN를 서버 환경에 구성하세요. 구성 형식과 위치는 클라이언트에 따라 다릅니다.

문제 해결

• 서버가 연결되지 않음: Node.js 및 npx이 클라이언트에서 사용 가능한지 확인한 다음 MCP 연결을 다시 시작하세요. 서버는 도구 정의를 로드하기 위해 docs-download.gologin.com에 대한 액세스도 필요합니다.
• API가 401 Unauthorized를 반환: 서버에 전달된 API_TOKEN과 GoLogin에서 토큰의 유효성을 확인하세요. 변경 후 연결을 다시 시작하세요.
• 도구 이름을 찾을 수 없음: 도구 목록을 새로 고치고 tools/list이 반환한 이름을 사용하세요. list_profiles 및 start_browser와 같은 이름은 기본 제공 별칭이 아닙니다.
• 클라우드 시작 실패: API 응답과 계정의 클라우드 액세스를 확인하세요. 로컬 MCP 시작은 자체적으로 컴퓨터에서 Orbita를 시작하지 않습니다.

개발

git clone https://github.com/gologinapp/gologin-mcp.git
cd gologin-mcp
npm ci
npm run build

API_TOKEN이 이미 구성된 상태에서 로컬 빌드를 실행하려면:

node dist/index.js

게시 전에 다음을 실행하세요:

npm run release:check

패키지에는 빌드된 서버, 패키지 메타데이터, README 및 라이선스만 포함됩니다. 릴리스 검사는 이 허용 목록을 확인하여 로컬 상태, 데이터베이스, 자격 증명 및 개발 파일이 추가 파일로 포함될 수 없도록 합니다. npm publish은 동일한 검사를 자동으로 실행합니다.

MCP 레지스트리 릴리스

server.json는 공식 MCP 레지스트리에서 io.github.gologinapp/gologin-mcp 아래에 이 서버를 설명합니다. npm 패키지는 mcpName에 동일한 식별자를 선언합니다.

package.json, package-lock.json 및 server.json의 버전을 일치시키세요. 확인된 npm 패키지를 먼저 게시한 다음 저장소의 Actions 탭에서 main에 Publish to MCP Registry를 실행하세요. 워크플로는 npm 릴리스에 올바른 레지스트리 식별자가 포함되어 있는지 확인하고 별도의 레지스트리 토큰 없이 GitHub OIDC를 사용하여 인증합니다. npm에는 게시하지 않습니다.

링크

• GoLogin
• GoLogin API 문서
• npm 패키지
• Glama 디렉토리

라이선스

MIT, 저작권 GoLogin.