Apify MCP Server
- 추천0
- GitHub 별17K
- 웹 스크래핑원격 연결라이선스MIT
Apify 공식 MCP 서버. 에이전트가 Apify Store의 수천 개 Actor로 웹 스크래핑 · 데이터 추출 · 브라우저 자동화를 해요(원격 · npx)
연결 · 설치 방법은 설치 탭에 정리했어요.
설명

Apify MCP 서버
에이전트를 AI용 도구의 가장 큰 마켓플레이스에 연결하세요.
공식 Apify Model Context Protocol(MCP) 서버는 https://mcp.apify.com에서 Apify Store의 수천 개 기성 Actor를 통해 AI 에이전트에 웹 스크래핑, 데이터 추출, 브라우저 자동화를 제공합니다.
Apify는 AI 에이전트가 바로 실행할 수 있는 도구의 마켓플레이스입니다. Apify MCP 서버에 한 번 연결하면 웹 가져오기, 검색 결과(SERP) 모니터링, 리드 발굴과 보강, 전자상거래 사이트와 소셜 미디어의 데이터 수집 같은 작업을 위해 에이전트가 고를 수 있는 수천 개의 도구가 생깁니다. 서버는 각 작업에 필요한 것만 불러옵니다.
에이전트는 Apify Store를 검색하고, Actor의 입력과 가격을 확인하고, 실행한 뒤, 구조화된 결과를 읽습니다. 그래서 사이트마다 별도의 MCP 서버를 설치할 필요가 없습니다. 호스팅 서버에는 OAuth로 연결하거나, @apify/actors-mcp-server npm 패키지로 stdio를 통해 로컬에서 실행할 수 있습니다.

목차
- 빠른 시작
- 클라이언트 설정
- 원격(호스팅) 서버와 로컬 MCP 서버
- 에이전트가 Apify Actor를 쓰는 방법
- 도구, 리소스, 프롬프트
- 불러올 도구 고르기
- UI 모드 설정
- 프롬프트 예시
- 가격과 한도
- 텔레메트리
- 문제 해결과 제한 사항
- FAQ
- 개발
- 기여하기
- 개인정보와 라이선스
- 더 알아보기
🚀 빠른 시작
- MCP 설정 도우미를 열고 클라이언트를 고른 뒤, 쓰고 싶은 도구를 선택합니다.
- 생성된 설정, 딥링크, 명령을 클라이언트에 복사합니다.
- 열리는 브라우저 창에서 Apify에 로그인합니다. 계정이 없으면 거기서 무료로 만들 수 있습니다.
호스팅 엔드포인트는 https://mcp.apify.com입니다. 클라이언트가 OAuth를 쓸 수 없다면 대신 Authorization: Bearer <APIFY_TOKEN> 헤더로 Apify API 토큰을 보내세요. 토큰은 비밀번호처럼 다루고 저장소에 올리지 마세요. Apify Console에서 토큰을 만들고 만든 직후에 복사하세요. 한 번만 보여 줍니다.
Claude Code, Codex, Cursor, GitHub Copilot 같은 코딩 에이전트를 쓰나요? 공식 Apify 플러그인이 이 MCP 서버를 Apify 에이전트 스킬과 함께 한 번에 설치해 줍니다.
🤖 클라이언트 설정
설정 도우미가 Claude Code, ChatGPT, Cursor, VS Code, GitHub Copilot CLI, Claude, Claude Desktop, Codex, OpenCode, Kiro 등 지원하는 각 클라이언트의 정확한 설정을 만들어 줍니다. 아래는 가장 흔한 경우입니다.

Claude Code
claude mcp add apify "https://mcp.apify.com" -t http
Claude Code는 서버를 처음 쓸 때 Apify 로그인 페이지를 엽니다. Apify 에이전트 스킬이 들어 있는 Apify 플러그인을 대신 설치하려면 /plugin marketplace add apify/apify-claude-code-plugin을 실행한 다음 /plugin install apify@apify와 /reload-plugins를 실행하세요.
ChatGPT
- ChatGPT 플러그인(https://chatgpt.com/plugins)을 열고 **+**를 누른 뒤 Add custom MCP server를 고릅니다.
- 이름을
Apify로 하고, 서버 URL에https://mcp.apify.com을 넣고, 인증은 OAuth를 고릅니다. - 위험 경고를 확인하고 I understand and want to continue를 누른 뒤 Create as a plugin을 누릅니다.
- Apify로 로그인하고, 도구를 확인한 뒤 플러그인을 설치합니다. API 토큰은 필요 없습니다.
- 새 대화를 시작하고
@를 입력한 뒤 Apify를 고릅니다.
Business, Enterprise, Edu 워크스페이스에서는 관리자나 소유자가 플러그인을 만들거나 게시해야 할 수 있습니다. 옵션이 보이지 않으면 워크스페이스 관리자에게 문의하세요. 서버의 도구가 바뀌면 플러그인을 열고 Refresh를 누르세요.
ChatGPT 데스크톱 앱은 Codex와 공유하는 로컬 MCP 설정을 씁니다. Settings > MCP servers > Add server로 가서 Streamable HTTP를 고르고 https://mcp.apify.com을 입력하세요. OpenAI의 커스텀 MCP 서버 안내를 보세요.
Cursor
설정 도우미의 원클릭 설치 링크를 쓰거나, Apify CLI가 API 토큰까지 넣어 설정을 쓰게 하세요.
apify mcp install cursor
같은 명령이 claude-code, vscode, codex, kiro, antigravity에서도 동작합니다.
VS Code와 GitHub Copilot
설정 도우미의 원클릭 설치 링크를 쓰거나, apify mcp install vscode를 실행하거나, MCP 설정에 https://mcp.apify.com을 HTTP 서버로 추가하세요.
{
"servers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com"
}
}
}
Claude
Apify는 Claude 커넥터로 제공됩니다. Settings > Connectors를 열고 커넥터 디렉터리에서 Apify를 찾아 연결하세요. Add custom connector를 골라 이름을 Apify로 하고 원격 MCP 서버 URL로 https://mcp.apify.com을 넣어도 됩니다. 안내가 나오면 Apify로 로그인하세요. 같은 커넥터가 Claude.ai와 Claude Desktop에서 동작합니다. Claude 안내를 보세요.
그 밖의 MCP 클라이언트(JSON 설정)
원격 서버와 OAuth를 지원하는 대부분의 클라이언트는 이런 설정을 받습니다.
{
"mcpServers": {
"apify": {
"url": "https://mcp.apify.com"
}
}
}
로컬 stdio(npx)
Node.js 22 이상이 필요합니다.
{
"mcpServers": {
"actors-mcp-server": {
"command": "npx",
"args": ["-y", "@apify/actors-mcp-server"],
"env": {
"APIFY_TOKEN": "YOUR_APIFY_TOKEN"
}
}
}
}
Apify Console에서 API 토큰을 만들고 만든 직후에 복사하세요. 한 번만 보여 줍니다.
apify login을 실행했다면 서버가 Apify CLI가 저장한 토큰도 읽을 수 있습니다. 모든 옵션은 npx @apify/actors-mcp-server --help로 볼 수 있습니다.
서버는 Docker MCP 카탈로그에도 올라 있고, 각 릴리스에는 이를 지원하는 클라이언트에서 원클릭 설치할 수 있는 MCP 번들 파일(apify-mcp-server.mcpb, 내려받기)이 들어 있습니다.
원격(호스팅) 서버와 로컬 MCP 서버
OAuth를 쓰는 호스팅 원격 MCP 서버를 권장합니다. MCP 프로세스를 내 컴퓨터에서 돌리고 싶을 때는 로컬 서버를 쓰세요. 어느 방식이든 Actor는 Apify 플랫폼에서 실행되고 결과도 거기에 저장됩니다. 클라이언트가 stdio만 지원한다면 mcp-remote(npm)로 호스팅 서버에 이어 붙일 수도 있습니다: npx mcp-remote https://mcp.apify.com.
호스팅 (https://mcp.apify.com) | 로컬 (npx @apify/actors-mcp-server) | |
|---|---|---|
| 전송 방식 | Streamable HTTP | stdio |
| 인증 | OAuth 또는 Bearer 토큰 | APIFY_TOKEN 환경 변수 또는 Apify CLI 로그인 |
| Actor 결과의 출력 스키마 추론 | 예 | 아니요 |
| 도구 선택 | tools URL 파라미터 | --tools 플래그 또는 TOOLS 환경 변수 |
| 업데이트 | 항상 최신 서버 | 설치한 npm 버전 |
에이전트가 Apify Actor를 쓰는 방법
Actor는 Apify 플랫폼의 서버리스 프로그램입니다. 각각 구글 지도 스크래핑, RAG용 웹사이트 크롤링, 소셜 미디어 게시물 수집 같은 특정 작업을 합니다. MCP 서버는 Actor를 에이전트가 찾아서 호출할 수 있는 도구로 바꿔 주기 때문에, 미리 하나씩 설정할 필요가 없습니다.
일반적인 작업은 네 단계로 진행됩니다.
search-actors가 작업에 맞는 후보 Actor를 Apify Store에서 찾습니다.fetch-actor-details가 Actor의 입력 스키마, README, 가격을 돌려주고, 요청하면 출력 스키마도 돌려줍니다.call-actor가 실행을 시작하고 끝날 때까지 기다립니다. 기본 30초, 최대 45초입니다. 실행 상태와 저장소 ID를 돌려주며, 스크래핑한 항목은 실행의 데이터셋에 남습니다.get-dataset-items가 실행의 데이터셋에서 결과를 읽습니다. 쪽 나누기에는limit과offset을 씁니다.
call-actor나 Actor 도구를 불러올 때마다 서버가 get-dataset-items, get-key-value-store-record, get-actor-run, abort-actor-run을 함께 추가합니다. 그래서 에이전트는 언제든 결과를 읽고, 기다리는 시간보다 오래 걸리는 실행도 확인할 수 있습니다.
특정 Actor를 그 자체로 도구로 내놓을 수도 있습니다. 예를 들어 apify/instagram-scraper입니다. 서버가 Actor의 입력 스키마로 도구의 파라미터를 만들기 때문에 에이전트가 무엇을 넘겨야 하는지 정확히 압니다. apify/web-fetch, apify/web-search, apify/rag-web-browser처럼 API 스키마가 있는 Server Actor는 실행을 시작하는 대신 그 API에 HTTP 요청을 한 번 보내는 도구가 됩니다.
자체 MCP 서버를 실행하는 Actor. 어떤 Actor는 그 자체가 MCP 서버입니다. fetch-actor-mcp-tool-list가 그 도구를 나열하고 call-actor-mcp-tool이 하나를 호출합니다. 이런 Actor를 도구 소스로 불러왔고 API 스키마가 없으면 그 도구들은 username--actor-name--tool-name 형태의 이름으로 노출됩니다. apify/web-search처럼 API 스키마가 있는 Actor는 대신 서버 도구를 얻고, call-actor-mcp-tool로 그 MCP 도구에 닿을 수 있습니다. Apify Store에는 독립 제작자의 MCP 관련 Actor도 올라 있습니다. 이들은 자체 README와 가격이 있는 별개의 제품입니다.
🛠️ 도구, 리소스, 프롬프트
어떤 Actor든 도구가 될 수 있고, 에이전트는 일하면서 새 Actor를 찾아냅니다. 기본으로 서버는 actors와 docs 카테고리, Actor 도구 둘(Web Search, Web Fetch), report-problem을 불러옵니다. 나머지는 카테고리나 도구 이름으로 직접 켜야 합니다.
도우미 도구
Actor 도구 외에 서버는 Apify 플랫폼용 도우미 도구를 제공합니다.
- Actor: Apify Store 검색, 내 계정의 Actor 목록, 상세 보기, MCP 서버를 실행하는 Actor의 도구 호출, Server Actor에 요청 보내기, 내 Actor 삭제.
- 문서: Apify와 Crawlee 문서를 검색하고 페이지를 컨텍스트로 가져오기.
- 실행과 저장소: 실행 목록, 조회, 로그 읽기, 데이터셋과 키-값 저장소 읽기.
- 작업과 스케줄: 저장된 Actor 작업과 그 공개 랜딩 페이지 관리, Actor와 작업을 자동으로 실행하는 스케줄 관리.
- 빌드와 버전: Actor 빌드, 빌드 로그 읽기, 파일로 버전 만들기 · 읽기 · 바꾸기 · 복사 · 삭제.
- Apify API: API 레퍼런스 검색, 오퍼레이션 조회, 데이터를 읽거나 바꾸는 요청 보내기.
사용할 수 있는 도구
기본 활성화 열의 표기:
- ✅ 기본 도구 세트에 들어 있음.
- ⚡
call-actor, Actor 도구,get-actor-run중 하나가 불러와지면 자동으로 추가됨. 기본 설정에서는 항상 해당됩니다. - ✅¹ 텔레메트리가 켜져 있고 클라이언트 이름에
claude,anthropic,local-agent-mode가 들어 있지 않을 때만 기본으로 제공됨.tools=report-problem이나tools=dev로 직접 고르면 어떤 클라이언트에도 제공되지만, 텔레메트리는 켜져 있어야 합니다.
| 도구 이름 | 카테고리 | 설명 | 기본 활성화 |
|---|---|---|---|
search-actors | actors | Apify Store에서 Actor를 검색합니다. | ✅ |
fetch-actor-details | actors | Actor의 입력 스키마, README(있으면 요약, 없으면 전체), 가격, Server Actor의 HTTP 오퍼레이션을 가져옵니다. 출력 스키마는 선택 사항입니다. | ✅ |
call-actor | actors | Actor를 실행하고 실행 상태와 저장소 ID를 돌려줍니다. 먼저 fetch-actor-details로 입력 스키마를 얻으세요. | ✅ |
fetch-actor-mcp-tool-list | actors | MCP 서버를 실행하는 Actor의 도구를 스키마, 어노테이션, 메타데이터와 함께 나열합니다. | ✅ |
call-actor-mcp-tool | actors | Actor의 MCP 서버에서 도구 하나를 호출하고 결과를 돌려줍니다. | ✅ |
send-server-actor-request | actors | Server Actor의 API 스키마에 문서화된 대로 API에 HTTP 요청을 한 번 보내고 응답을 돌려줍니다. | ✅ |
get-actor-run | runs | Actor 실행의 상세 정보를 가져옵니다. | ⚡ |
get-dataset-items | storage | 데이터셋의 항목을 필터링과 쪽 나누기로 읽습니다. | ⚡ |
get-key-value-store-record | storage | 키-값 저장소에서 키에 저장된 값을 가져옵니다. | ⚡ |
abort-actor-run | runs | 실행 중인 Actor를 중단합니다(정상 종료 선택 가능). | ⚡ |
search-apify-docs | docs | 관련 페이지를 찾아 Apify와 Crawlee 문서를 검색합니다. | ✅ |
fetch-apify-docs | docs | URL로 문서 페이지의 전체 내용을 가져옵니다. | ✅ |
apify--web-search | Actor(불러올 도구 고르기 참고) | 웹을 검색해 결과 한 쪽(제목, URL, 스니펫)을 돌려줍니다. | ✅ |
apify--web-fetch | Actor(불러올 도구 고르기 참고) | URL을 가져와 내용을 Markdown, 텍스트, HTML 등으로 돌려줍니다. | ✅ |
report-problem | dev | Apify 도구나 Actor의 문제를 Apify 팀에 알립니다. | ✅¹ |
apify--rag-web-browser | Actor(불러올 도구 고르기 참고) | 웹을 검색해 상위 결과의 내용을 돌려줍니다. | |
get-actor-list | 없음(이름으로 선택: tools=get-actor-list) | 내가 소유하거나 공유받은 Actor를 비공개 포함해 나열합니다. | |
delete-actor | 없음(이름으로 선택: tools=delete-actor) | 내 계정의 Actor를 영구 삭제합니다. 공개 Actor는 먼저 비공개로 돌려야 합니다. | |
get-actor-run-list | runs | Actor와 상태로 걸러 Actor 실행을 나열합니다. | |
get-actor-run-log | runs | Actor 실행의 로그를 읽습니다. | |
get-dataset | storage | 데이터셋의 메타데이터를 가져옵니다. | |
get-dataset-schema | storage | 데이터셋 항목으로 JSON 스키마를 만듭니다. | |
get-dataset-list | storage | 내 계정의 데이터셋을 나열합니다. | |
get-key-value-store | storage | 키-값 저장소의 메타데이터를 가져옵니다. | |
get-key-value-store-keys | storage | 키-값 저장소의 키를 나열합니다. | |
get-key-value-store-list | storage | 내 계정의 키-값 저장소를 나열합니다. | |
create-actor-task | tasks | 저장된 Actor 작업(이름이 있고 재사용할 수 있는 Actor 설정)을 만듭니다. | |
get-actor-task | tasks | 저장된 Actor 작업과 게시 상태, 공개 표시 설정을 가져옵니다. | |
update-actor-task | tasks | 작업의 입력, 실행 옵션, 공개 표시 설정을 바꿉니다. | |
publish-actor-task | tasks | 작업을 공개 랜딩 페이지에 게시합니다. | |
unpublish-actor-task | tasks | 작업을 공개 랜딩 페이지에서 내립니다. | |
create-schedule | schedules | cron 표현식으로 Actor나 작업을 실행하는 스케줄을 만듭니다. | |
get-schedule | schedules | 스케줄과 cron 표현식, 상태, 실행하는 동작을 가져옵니다. | |
update-schedule | schedules | 스케줄의 cron 표현식, 시간대, 활성 상태, 동작을 바꿉니다. | |
delete-schedule | schedules | 스케줄을 삭제합니다. | |
build-actor | builds | Actor 버전을 빌드하고 빌드가 끝날 때까지 정해진 시간 동안 기다립니다. | |
get-actor-build | builds | Actor 빌드의 상태를 가져옵니다. | |
get-actor-build-list | builds | 계정의 빌드나 한 Actor의 빌드를 모든 상태로, 최신순으로 나열합니다. | |
get-actor-build-log | builds | Actor 빌드의 로그를 읽습니다. | |
get-actor-version | versions | Actor 버전의 파일 목록(해시 포함)과 요청한 파일의 내용을 가져옵니다. | |
create-actor | versions | 파일로 내 계정에 비공개 Actor를 만들고, 선택하면 빌드도 시작합니다. | |
update-actor-version | versions | Actor 버전의 파일을 한 번에(전부 되거나 전부 안 되게) 쓰고, 고치고, 지웁니다. | |
create-actor-version | versions | 파일이나 다른 버전의 복사본으로 Actor에 버전을 추가하고, 선택하면 빌드도 시작합니다. | |
delete-actor-version | versions | Actor 버전을 삭제합니다. 그 빌드와 태그는 남습니다. | |
apify-api-search | api | 키워드로 Apify API 레퍼런스를 검색합니다. 오퍼레이션마다 메서드, 경로, 문서 페이지를 돌려줍니다. | |
apify-api-details | api | 경로에 있는 Apify API 오퍼레이션의 파라미터와 요청 본문 스키마를 가져옵니다. | |
apify-api-read | api | Apify CLI의 apify api처럼 Apify API 경로에 GET 요청을 보냅니다. 유료 실행을 시작하는 동기 실행 엔드포인트로의 GET은 거절합니다. | |
apify-api-write | api | Apify CLI의 apify api처럼 아무 Apify API 경로에나 JSON 본문으로 POST, PUT, PATCH, DELETE 요청을 보냅니다. |
tasks 카테고리는 저장된 Actor 작업을 관리합니다. MCP Tasks 프로토콜과는 관계가 없습니다. 각 도구의 전체 설명은 도구 레퍼런스에 있습니다.
도구 어노테이션
모든 도구에는 title, readOnlyHint, openWorldHint가 있습니다. readOnlyHint는 데이터를 읽기만 하는 도구에서 true입니다. Actor 도구는 권한이 제한된 Apify 관리 Actor이면서 비밀, 쓰기 가능한 저장소, MCP 커넥터, 코드를 받는 입력이 없을 때만 이 값을 얻고, 나머지 Actor 도구는 파괴적인 것으로 표시됩니다. openWorldHint는 call-actor처럼 Apify 플랫폼 밖에 닿는 도구에서 true이고, 플랫폼 안에서만 동작하는 도구에서는 false입니다.
프롬프트와 리소스
등록된 프롬프트는 아직 없어서 prompts/list는 빈 목록을 돌려줍니다. resources/read는 Apify API의 GET URL(https://api.apify.com/v2/...)을 받아 세션의 Apify 토큰으로 응답 본문을 돌려주며, 256 KB까지 인라인으로 담습니다. 내 데이터는 resources/list에 나열되지 않고, resources/templates/list가 자주 쓰는 형태를 쪽 나누기 파라미터와 함께 보여 줍니다.
불러올 도구 고르기
tools 파라미터는 카테고리, 도구 이름, Actor 이름을 쉼표로 구분해 받습니다. 이 값을 지정하면 기본값은 빠지고 나열한 것만 불러옵니다. 목록에 call-actor나 Actor가 들어 있으면 ⚡ 실행·저장소 도구도 함께 불러옵니다. 선택을 만드는 가장 쉬운 방법은 설정 도우미입니다.
호스팅 서버:
https://mcp.apify.com?tools=actors,docs,apify/web-search,apify/web-fetch
로컬 서버:
npx @apify/actors-mcp-server --tools actors,docs,apify/web-search,apify/web-fetch
에이전트에 Actor 하나만 주려면 그것만 나열하세요. 에이전트는 그 Actor의 도구와 결과를 읽는 데 필요한 ⚡ 도구 넷을 얻습니다.
https://mcp.apify.com?tools=apify/instagram-scraper
운영 환경에서는 도구를 고정하세요. 기본 도구 세트는 버전이 바뀌면 달라질 수 있습니다. 인터페이스가 안정적이어야 한다면
tools를 직접 지정하세요.
예전 설정과의 호환
apify/web-search가 기본 도구에서apify/rag-web-browser를 대체했습니다.apify--rag-web-browser를 계속 쓰려면tools목록에apify/rag-web-browser를 추가하거나, 예전 기본 카테고리와 Actor를 위해tools=actors,docs,apify/rag-web-browser,apify/web-fetch로 지정하세요.actorsURL 파라미터와--actors플래그도 계속 동작합니다.tools에 합쳐지므로?actors=apify/web-fetch는?tools=apify/web-fetch와 같습니다.enableAddingActors,enable-adding-actors,enableActorAutoLoading은 없어졌고 무시됩니다. 동적 Actor 호출은call-actor가 맡으며, 기본actors카테고리에 들어 있습니다.add-actor,experimental,preview선택자는 폐기되어 아무것도 불러오지 않습니다.call-actor나actors카테고리를 쓰세요.get-actor-log는get-actor-run-log로,source카테고리는versions로 이름이 바뀌었습니다. 예전 이름은 아무것도 불러오지 않습니다.call-actor는 더 이상 MCP 서버 Actor의 도구를 호출하지 않습니다.actorName:toolName형태는 거절됩니다.actor,tool,arguments를 넣어call-actor-mcp-tool을 쓰세요.call-actor는 입력 스키마가 있는 MCP 서버 Actor의 실행은 여전히 시작하지만, 입력 스키마가 없는 것은 거절합니다.call-actor만 고른 선택에는call-actor-mcp-tool을 추가해야 합니다.fetch-actor-details는 더 이상 MCP 서버 Actor의 도구를 나열하지 않으며output.mcpTools는 무시됩니다. 정의를structuredContent.tools로 돌려주는fetch-actor-mcp-tool-list를 쓰세요.fetch-actor-details만 고른 선택에는fetch-actor-mcp-tool-list를 추가해야 합니다.- API 스키마가 있는 Actor(Server Actor)를 고르면 실행을 시작하는 도구 대신
method,path,query인수로 그 API에 HTTP 요청 한 번을 보내는 도구가 생깁니다. 그 Actor가 MCP 서버이기도 하면 선택해도 MCP 도구는 더 이상 불러오지 않으니call-actor-mcp-tool을 쓰세요.call-actor는 입력 스키마가 있는 Actor의 실행은 여전히 시작합니다. 선택한apify/rag-web-browser도GET /search로 같은 방식으로 제공됩니다. apify--web-fetch는 실행을 시작하는 대신 Web Fetch Actor의 API에 HTTP 요청 한 번을 보내고 HTTP 응답을 돌려줍니다. 인수는method,path,query이고POST /에는body도 있습니다. 예:{"method": "GET", "path": "/", "query": {"url": "https://example.com", "formats": ["markdown", "links"]}}.apify--web-search는 실행을 시작하는 대신 Web Search Actor의 API에 HTTP 요청 한 번을 보내고 HTTP 응답을 돌려줍니다. 인수는method,path,query이고POST /에는body도 있습니다. 예:{"method": "GET", "path": "/", "query": {"query": "AI agent payment protocols", "maxResults": 5}}.call-actor는 이 Actor의 실행을 여전히 시작하고,call-actor-mcp-tool은 그searchMCP 도구를 호출합니다.
UI 모드 설정
ui 파라미터는 MCP Apps 위젯 도구를 제어합니다. UI 모드를 켜면 서버가 기본 도구 옆에 search-actors-widget과 fetch-actor-details-widget을 추가하고, 기본 도구는 계속 표준 응답을 돌려줍니다. 기본값(auto)에서는 클라이언트가 MCP Apps를 지원하면 UI 모드가 켜집니다.
| 값 | 동작 |
|---|---|
auto(기본) | 클라이언트가 MCP Apps를 지원하면 위젯 도구를 추가 |
true, on, apps | 위젯 도구를 항상 추가 |
false, off, default | 위젯 도구 없음 |
호스팅 서버:
https://mcp.apify.com?tools=actors,docs&ui=true
로컬 서버(CLI 플래그 또는 UI_MODE 환경 변수):
npx @apify/actors-mcp-server --ui true
UI_MODE=true npx @apify/actors-mcp-server
💬 프롬프트 예시
평범한 말로 요청하세요. 에이전트가 알맞은 Actor를 찾고, 입력과 가격을 확인하고, 실행한 뒤 결과를 읽습니다. 가장 흔한 작업은 이런 프롬프트들입니다.
| 용도 | 프롬프트 예시 | Actor 예시 |
|---|---|---|
| 웹 리서치 | "이번 주에 사람들이 X에서 자율 AI 에이전트에 대해 한 말을 찾아서 핵심 동향을 요약해 줘." | Tweet Scraper V2 |
| 웹 검색과 읽기 | "Notion, Coda, Airtable의 현재 요금제를 비교하고 10명 팀에 가장 싼 곳을 알려 줘." | Web Search, Web Fetch |
| 검색 결과(SERP) | "미국에서 'best CRM for startups'의 구글 상위 20개 결과를 가져와 누가 어디에 노출되는지 보여 줘." | Google Search Results Scraper |
| 리드 발굴 | "텍사스 오스틴의 치과를 구글 지도에서 찾아 전화번호, 웹사이트, 평점과 함께 알려 줘." | Google Maps Scraper |
| LinkedIn 프로필 | "이 LinkedIn 프로필 20개의 현재 직함, 회사, 경력을 가져와 줘." | LinkedIn Profile Scraper |
| LinkedIn 회사 게시물 | "Apify의 LinkedIn 회사 페이지에서 최신 게시물 30개를 반응 수와 함께 가져와 줘." | LinkedIn Company Posts Scraper |
| 리뷰 분석 | "이 호텔의 구글 지도 최신 리뷰 100개를 가져와 불만을 주제별로 묶어 줘." | Google Maps Reviews Scraper |
| 소셜 미디어 모니터링 | "@nasa의 Instagram 최신 게시물 50개를 좋아요와 댓글 수와 함께 가져와 줘." | Instagram Scraper |
| 트렌드 리서치 | "이번 주 #skincare 해시태그에서 조회수가 가장 높은 TikTok 영상을 찾아 줘." | TikTok Scraper |
| 전자상거래 | "아마존에서 평점이 가장 높은 무선 이어폰 10개를 가격과 리뷰 수와 함께 나열해 줘." | Amazon Product Scraper |
| 지식 베이스와 RAG | "docs.example.com을 크롤링해서 모든 페이지를 벡터 데이터베이스에 올릴 수 있는 Markdown으로 바꿔 줘." | Website Content Crawler |
후속 요청도 됩니다. "그 실행의 다음 10개 결과를 보여 줘"라고 하면 에이전트가 더 큰 offset으로 get-dataset-items를 다시 호출합니다. schedules 카테고리를 불러왔다면 "그 구글 지도 검색을 매주 월요일 오전 9시에 실행해 줘"로 스케줄이 만들어집니다.
💰 가격과 한도
- MCP 서버에 연결하는 것은 무료입니다. Actor 실행은 각 Actor의 가격에 따라 내 Apify 계정에 청구되며,
fetch-actor-details가 실행 전에 가격을 보여 줍니다. Apify 무료 플랜에는 매달 $5의 플랫폼 사용량이 포함됩니다. - 실행 하나의 비용 상한을 두려면
call-actor의callOptions에maxTotalChargeUsd(이벤트당 과금 Actor) 또는maxItems(결과당 과금 Actor)를 넘기세요.timeout과memory는 실행 시간과 메모리를 제한하며 가격을 제한하지 않습니다. - 호스팅 서버는 계정당 초당 최대 20개 요청을 받습니다.
search-actors는 플랫폼의 에이전트 안전 필터를 통과한 무료 Actor와 이벤트당 과금 Actor만 돌려주므로, 대여형과 결과당 과금 Actor는 검색에 나오지 않습니다. 전체 권한 Actor는 한 번 승인이 필요하고, 승인 전에는call-actor가 승인 링크가 든 오류를 돌려줍니다.- 일부 도구는 Apify 계정 없이도 동작합니다:
search-actors,fetch-actor-details,search-apify-docs,fetch-apify-docs,apify-api-search,apify-api-details. 이것들만 골라(예:https://mcp.apify.com?tools=search-actors) 쓰면 호스팅 서버가 토큰 없이 연결을 받아 줍니다.
🪙 에이전트 결제(실험). 에이전트가 Apify 계정 없이 Actor 실행 비용을 낼 수 있습니다. AGI가 x402, MPP, Skyfire 결제와 맞바꿔 한도가 정해진 선불 Apify API 토큰을 팝니다. 에이전트는 이 토큰을
mcp.apify.com에 쓰는 일반 Bearer 토큰으로 사용하며, 제한된 권한을 쓰는 어떤 Actor에도 쓸 수 있습니다. 지원하는 결제 방법과 한도는 에이전트 결제 문서를, 프로토콜 세부는 agi.apify.com/AGENTS.md를 보세요.
📡 텔레메트리
Apify MCP 서버는 사용 패턴을 이해하고 서비스를 개선하기 위해 도구 호출에 대한 텔레메트리를 수집합니다. 텔레메트리는 기본으로 켜져 있습니다. 텔레메트리가 켜져 있으면 Apify Store의 Actor 검색은 MCP 세션 ID의 SHA-256 해시 앞 16진수 12자를 _traceId로 보내고, 도구 호출 이벤트에는 trace_id로 담깁니다. search-actors는 모델이 쓴 검색 이유 한 문장인 _useCase도 보내며, Apify는 이를 Store 검색 결과를 개선하는 데 씁니다. stdio 전송은 오류 추적에 Sentry도 쓰는데, Apify 팀이 문제를 더 빨리 찾아 고치는 데 도움이 됩니다.
Sentry를 포함해 끄려면 telemetry-enabled URL 파라미터나 --telemetry-enabled CLI 플래그를 false로 하거나 TELEMETRY_ENABLED=false를 설정하세요. CLI 플래그가 환경 변수보다 우선합니다.
https://mcp.apify.com?telemetry-enabled=false
npx @apify/actors-mcp-server --telemetry-enabled=false
TELEMETRY_ENABLED=false npx @apify/actors-mcp-server
🐛 문제 해결과 제한 사항
- 로컬 서버가 시작되지 않아요. Node.js 버전을 확인하세요. 패키지는 Node.js 22 이상이 필요합니다.
- 인증이 실패해요. 다시 연결해서 클라이언트가 OAuth 과정을 반복하게 하거나, Bearer 토큰으로 바꾸세요. 로컬 서버는
APIFY_TOKEN이 셸이 아니라 클라이언트의 서버 설정에 들어 있는지 확인하세요. - VS Code가 OAuth 앱이 등록되지 않았다고 해요. Authentication: Remove Dynamic Authentication Providers를 실행하고 Apify를 고른 뒤 다시 로그인하세요.
- 클라이언트 기능이 달라요. 어떤 MCP 클라이언트든 연결할 수 있지만, 동적 도구 목록, OAuth, MCP Apps 지원은 클라이언트마다 다릅니다.
- Actor 입력이 올바르지 않아요. 잘못된 입력 때문에
call-actor가 실패하면 오류에 Actor의 입력 스키마가 들어 있어서, 에이전트가 입력을 고쳐 다시 시도할 수 있습니다.
서버가 Actor 입력 스키마를 맞추는 방법
서버는 더 많은 클라이언트와 모델이 쓸 수 있도록 Actor 입력 스키마를 조정합니다.
- 500자를 넘는 설명은 마지막 완전한 문장에서 잘리고
[Description truncated]로 표시됩니다. - 열거형(enum)은 합쳐서 2,000자까지는 그대로 유지됩니다. 더 큰 열거형은 예시 값이 든 짧은 설명으로 바뀝니다.
- 필수 필드는 JSON Schema의
required목록을 무시하는 프레임워크를 위해 설명 앞에REQUIRED가 붙습니다. - 프록시 설정이나 요청 목록 같은 특수한 입력에는 중첩 속성을 만듭니다.
- 빠진 배열 항목 형식은 항목 형식, 프리필, 기본값, 에디터 형식의 순서로 추론합니다.
- 프리필과 기본값은 JSON Schema
examples를 무시하는 클라이언트를 위해 설명에 예시로 복사됩니다.
더 도움이 필요하면 MCP 문서를 보거나 이슈를 열어 주세요.
❓ FAQ
MCP 서버가 뭔가요? MCP 서버는 Model Context Protocol을 통해 AI 에이전트에 도구와 데이터를 제공합니다. Model Context Protocol은 Claude, ChatGPT, Cursor 같은 클라이언트가 지원하는 열린 표준입니다. 에이전트는 한 번 연결해 두고, 작업에 필요할 때 서버의 도구를 호출합니다. Apify MCP 서버의 도구는 Apify Store의 Actor입니다.
Apify MCP 서버가 뭔가요? Apify의 공식 Model Context Protocol 서버입니다. AI 에이전트가 Apify Store를 검색하고, 웹 스크래핑, 데이터 추출, 브라우저 자동화를 하는 Actor를 실행하고, 구조화된 결과를 읽을 수 있게 합니다.
웹 스크래핑용 MCP 서버로 언제 좋은가요? 에이전트가 여러 사이트의 데이터가 필요할 때입니다. 하루는 구글 지도, 다음 날은 Instagram이나 온라인 쇼핑몰인 경우가 전형적입니다. 스크래퍼를 직접 만들고 유지하는 대신, 에이전트가 사이트마다 Apify Store에서 기성 Actor를 고릅니다. 각 Actor는 해당 사이트용 웹 스크래핑 API처럼 동작하고, 확장, 프록시, 결과 저장은 Apify 플랫폼이 맡습니다.
Playwright MCP와는 어떻게 다른가요? Playwright MCP는 클릭과 페이지 스냅샷으로 내 컴퓨터의 브라우저를 단계별로 조종합니다. Apify MCP 서버는 Apify 클라우드에서 Actor를 실행합니다. 각 Actor가 사이트별 JavaScript 렌더링, 프록시, 차단을 처리하고 구조화된 결과를 돌려주므로, 에이전트는 브라우저를 조작하는 대신 데이터를 요청합니다. 많은 에이전트가 둘을 함께 씁니다.
ChatGPT나 Claude로 웹사이트를 스크래핑할 수 있나요?
네. ChatGPT, Claude, Claude Code를 https://mcp.apify.com에 연결한 뒤 평범한 말로 요청하세요. 모델이 알맞은 Actor를 찾아 실행하고 결과를 읽습니다.
무료인가요? 연결은 무료이고, 일부 탐색 도구는 계정 없이도 동작합니다. Actor 실행은 각 Actor의 가격대로 Apify 계정에 청구되며, 무료 플랜에는 매달 $5의 플랫폼 사용량이 포함됩니다.
API 토큰이 필요한가요?
호스팅 서버에서는 필요 없습니다. OAuth가 브라우저로 로그인시켜 주기 때문입니다. 로컬 서버는 APIFY_TOKEN이나 Apify CLI 로그인이 필요합니다.
에이전트가 할 수 있는 일과 쓰는 돈을 제한할 수 있나요?
네. tools 파라미터로 도구를 고르거나 Actor 하나만 내놓으세요. 실행 하나의 비용 상한은 call-actor 옵션에 이벤트당 과금 Actor는 maxTotalChargeUsd, 결과당 과금 Actor는 maxItems를 넘겨 정합니다.
🔧 개발
이 저장소에는 npm에 @apify/actors-mcp-server로 게시되는 오픈소스 서버 패키지가 들어 있습니다. mcp.apify.com의 호스팅 서비스는 별도의 비공개 저장소에서 이 핵심 로직으로 돌아갑니다.
Node.js 22 이상과 pnpm이 필요합니다.
pnpm install
pnpm run build
pnpm run dev # http://localhost:3001의 Streamable HTTP 서버, 위젯은 핫 리로드
pnpm run inspector:stdio # stdio 서버에 MCP Inspector 연결
개발용 HTTP 서버는 환경 변수에서 APIFY_TOKEN을 읽지 않습니다. 예를 들어 MCP Inspector에서 Authorization: Bearer 헤더나 ?token= 쿼리 파라미터로 토큰을 넘기세요.
풀 리퀘스트의 카나리 빌드를 pkg.pr.new에 게시하려면 PR에 beta 라벨을 붙이세요.
프로젝트 구조, 도구 로딩 단계, Node.js 버전 정책, 테스트는 DEVELOPMENT.md에 있습니다.
🤝 기여하기
버그 제보, 기능 요청, 문서 수정을 환영합니다. 버그는 재현 단계를 적어 이슈를 열고, 기능은 해결하려는 문제와 그 문제를 겪는 사람을 설명해 주세요. 오타, 깨진 링크, 틀린 명령은 바로 풀 리퀘스트를 보내세요. 코드는 메인테이너가 맡아도 좋다고 초대한 이슈에서만 작업하세요. 요청받지 않은 풀 리퀘스트는 닫힙니다.
시작하기 전에 AI의 도움을 받은 기여 규칙을 포함해 CONTRIBUTING.md를 읽어 주세요.
🔒 개인정보와 라이선스
요청과 Actor 입력은 내가 호출하는 Actor를 실행하기 위해 Apify API로 갑니다. Apify는 그 Actor를 실행하는 데 필요한 범위를 넘어서 제3자와 공유하지 않습니다. 데이터 수집과 보관에 대한 자세한 내용은 Apify 법적 문서를 보세요.
이 프로젝트는 MIT 라이선스입니다.
📚 더 알아보기
- MCP 문서: 인증, 도구 레퍼런스, 고급 설정
- AI 에이전트를 위한 Apify: MCP, 플러그인, 에이전트 스킬, CLI, 기계가 읽는 문서 중 고르기
- Apify 에이전트 스킬: 안내형 다단계 워크플로,
npx skills add apify/agent-skills로 설치 - Apify CLI: 터미널에서 Actor 실행과 빌드
- Model Context Protocol
- MCP 입문
- Apify Actor로 MCP 쓰는 법
- 웨비나: Apify에서 MCP 서버 만들고 수익화하기