Exa Websets MCP 서버

Exa의 Websets API를 Claude Desktop, Cursor, Windsurf 및 기타 MCP 호환 클라이언트와 통합하는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

Websets란 무엇인가요?

Websets는 자동으로 발견, 검증되고 사용자 지정 데이터로 강화될 수 있는 웹 엔티티(기업, 인물, 연구 논문)의 컬렉션입니다. AI 웹 조사를 기반으로 하는 스마트하고 스스로 업데이트되는 스프레드시트라고 생각하시면 됩니다.

주요 기능:

• 🔍 자동화된 검색: 자연어 기준에 맞는 엔티티 찾기

• 📊 데이터 강화: AI 에이전트를 사용하여 사용자 지정 정보 추출

• 🎯 검증: 엔티티가 귀하의 기준을 충족하는지 AI가 검증

• 🔗 웹훅: 컬렉션 업데이트에 대한 실시간 알림

• 📥 가져오기: 자체 CSV 데이터를 Websets로 가져와 강화 또는 범위 지정

Related MCP server: Exa Websets MCP Server

사용 가능한 도구

이 MCP 서버는 다음과 같은 도구를 제공합니다:

Webset 관리

항목 관리

검색 작업

강화 작업

웹훅

가져오기

이벤트

설치

Smithery를 통한 설치

Smithery를 통해 Exa Websets를 자동으로 설치하려면:

npx -y @smithery/cli install @exa-labs/websets-mcp-server

사전 요구 사항

• Node.js v18 이상

• Claude Desktop, Cursor 또는 기타 MCP 호환 클라이언트

• exa.ai에서 발급받은 Exa API 키

Claude Code 사용 (권장)

Websets MCP를 설정하는 가장 빠른 방법:

claude mcp add websets -e EXA_API_KEY=YOUR_API_KEY -- npx -y websets-mcp-server

YOUR_API_KEY를 귀하의 Exa API 키로 바꾸십시오.

NPX 사용

# Install globally
npm install -g websets-mcp-server

# Or run directly with npx
npx websets-mcp-server

구성

Claude Desktop 구성

1. 개발자 모드 활성화

   • Claude Desktop 열기

   • 메뉴 클릭 → 개발자 모드 활성화

   • 설정 → 개발자 → 구성 편집으로 이동

2. 구성 파일에 추가:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "websets": {
         "command": "npx",
         "args": [
           "-y",
           "websets-mcp-server"
         ],
         "env": {
           "EXA_API_KEY": "your-api-key-here"
         }
       }
     }
   }

3. Claude Desktop 재시작

   • Claude Desktop을 완전히 종료

   • 다시 시작

   • 🔌 아이콘을 확인하여 연결 확인

Cursor 및 Claude Code 구성

HTTP 기반 구성을 사용하십시오. Authorization 헤더에 Exa API 키를 Bearer 토큰으로 전달하십시오(또는 대체 방법으로 ?exaApiKey=... 쿼리 매개변수 사용):

{
  "mcpServers": {
    "websets": {
      "type": "http",
      "url": "https://websetsmcp.exa.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_EXA_API_KEY"
      }
    }
  }
}

도구 스키마 참조

⚠️ AI 호출자를 위한 중요 사항: 정확한 매개변수 형식 및 예제는 TOOL_SCHEMAS.md를 참조하십시오.

주요 스키마 규칙:

• criteria는 객체 배열이어야 합니다: [{description: "..."}] (문자열 배열이 아님)

• entity는 객체여야 합니다: {type: "company"} (문자열이 아님)

• options는 객체 배열이어야 합니다: [{label: "..."}] (문자열 배열이 아님)

이 형식들은 모든 도구에서 일관성을 보장하며 Websets API 사양과 일치합니다.

사용 예시

구성이 완료되면 Claude에게 Websets와 상호 작용하도록 요청할 수 있습니다:

웹셋 생성

Create a webset of AI startups in San Francisco with 20 companies. 
Add enrichments for revenue, employee count, and funding stage.

웹셋 나열 및 보기

List all my websets and show me the details of the one called "AI Startups"

항목 관리

Show me the first 10 items from my "AI Startups" webset with all their enrichment data

항목 추가

Run another search on my "AI Startups" webset for 20 more companies focused on
enterprise voice agents, appending to the existing items

고급 강화

Add an enrichment to my webset that extracts the company's latest product launch 
and the CEO's LinkedIn profile

워크플로우 예시

기업 조사 데이터베이스를 구축하기 위한 전체 워크플로우입니다:

1. 컬렉션 생성:

   Create a webset called "SaaS Companies" that searches for 
   "B2B SaaS companies with $10M+ revenue"

2. 강화 추가:

   Add enrichments to extract: annual recurring revenue, number of customers, 
   primary market segment, and tech stack used

3. 이벤트 구독:

   Create a webhook to https://example.com/hook subscribed to
   webset.search.completed and webset.enrichment.completed

4. 결과 보기:

   Show me all items with their enrichment data, sorted by revenue

도구 세부 정보

create_webset

선택적 자동 채우기 및 강화 기능을 갖춘 새로운 웹셋 컬렉션을 생성합니다.

매개변수:

• externalId (선택 사항): 웹셋에 대한 귀하만의 식별자 (최대 300자)

• searchQuery (선택 사항): 엔티티를 찾기 위한 자연어 쿼리

• searchCount (선택 사항): 찾을 엔티티 수 (기본값: 10, 최소: 1)

• searchEntity (선택 사항): 검색할 엔티티 유형 (예: {type: "company"}). "custom" 유형의 경우 description을 포함하십시오.

• searchCriteria (선택 사항): 추가 필터링 기준 — [{description: "..."}] (최대 5개)

• searchBehavior (선택 사항): "override" (기본값)는 기존 항목을 대체하고, "append"는 기존 항목에 추가합니다.

• searchExclude (선택 사항): 결과를 제외할 가져오기/웹셋 — [{source: "webset"|"import", id: "..."}]

• searchScope (선택 사항): 기존 가져오기 또는 웹셋으로 검색 범위 지정 — relationship을 사용한 홉 검색 활성화

• searchRecall (선택 사항): 검색에 대한 리콜 메트릭을 계산할지 여부

• searchMaxPeoplePerCompany (선택 사항): 인물 검색 시 고용주당 인물 수에 대한 소프트 캡

• searchMetadata (선택 사항): 검색과 연결할 키-값 메타데이터

• enrichments (선택 사항): 각 항목에 대해 자동으로 추출할 데이터 강화

• metadata (선택 사항): 웹셋과 연결할 키-값 메타데이터

• excludes (선택 사항): 전역 제외 — 이 웹셋의 모든 작업에서 결과가 생략되는 소스

참고: 웹셋 자체에는 최상위 name 또는 description 매개변수가 없습니다. 생성 후 title과 함께 update_webset을 사용하거나, 임의의 키-값 쌍을 첨부하려면 metadata를 사용하십시오.

예시:

{
  "externalId": "tech-unicorns-2024",
  "searchQuery": "Technology companies valued over $1 billion",
  "searchCount": 50,
  "searchEntity": {"type": "company"},
  "searchCriteria": [
    {"description": "Valued at over $1 billion"},
    {"description": "Technology sector"}
  ],
  "enrichments": [
    {
      "description": "Current company valuation in USD",
      "format": "number"
    },
    {
      "description": "Names of company founders",
      "format": "text"
    },
    {
      "description": "Company stage",
      "format": "options",
      "options": [
        {"label": "Series A"},
        {"label": "Series B"},
        {"label": "Series C+"},
        {"label": "Public"}
      ]
    }
  ]
}

create_enrichment

각 웹셋 항목에서 사용자 지정 정보를 추출하기 위한 새로운 데이터 강화를 추가합니다.

매개변수:

• websetId: 웹셋의 ID

• description: 추출할 내용에 대한 자세한 설명

• format (선택 사항): "text", "date", "number", "options", "email", "phone", "url" 중 하나 — 생략 시 자동 선택됨

• options (선택 사항): format이 "options"일 때, 강화 에이전트가 선택할 선택지 — [{label: "..."}]

• metadata (선택 사항): 이 강화와 연결할 키-값 메타데이터

예시:

{
  "websetId": "webset_abc123",
  "description": "Total number of full-time employees as of the most recent data",
  "format": "number"
}

모니터(예약된 새로 고침/검색)는 기본 Websets API에 의해 노출되지만, 현재 이 서버에서는 MCP 도구로 제공되지 않습니다. Websets API 또는 websets.exa.ai를 통해 직접 모니터를 구성하십시오.

API 엔드포인트

이 서버는 https://api.exa.ai/websets/v0에서 Exa의 Websets API에 연결합니다.

전체 API 문서: docs.exa.ai/reference/websets

고급 구성

특정 도구만 활성화

특정 도구만 활성화하려면 enabledTools 구성을 사용하십시오:

{
  "mcpServers": {
    "websets": {
      "command": "npx",
      "args": [
        "-y",
        "websets-mcp-server",
        "--tools=create_webset,list_websets,list_webset_items"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

디버그 모드

문제를 해결하기 위해 디버그 로깅을 활성화하십시오:

{
  "mcpServers": {
    "websets": {
      "command": "npx",
      "args": [
        "-y",
        "websets-mcp-server",
        "--debug"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

문제 해결

연결 문제

1. API 키가 유효한지 확인하십시오.

2. API 키 주변에 공백이나 따옴표가 없는지 확인하십시오.

3. MCP 클라이언트를 완전히 다시 시작하십시오(창을 닫는 것뿐만 아니라).

4. 오류 메시지에 대해 MCP 로그를 확인하십시오.

API 속도 제한

Websets API에는 다음과 같은 제한이 있습니다:

• exa.ai/dashboard에서 플랜 제한을 확인하십시오.

• 대규모 웹셋에는 페이지네이션을 사용하십시오.

• 대시보드에서 API 사용량을 모니터링하십시오.

일반적인 오류

• 401 Unauthorized: 유효하지 않거나 누락된 API 키

• 404 Not Found: 웹셋 ID가 존재하지 않거나 삭제됨

• 422 Unprocessable: 유효하지 않은 쿼리 또는 기준 형식

• 429 Rate Limited: 너무 많은 요청, 잠시 후 다시 시도

리소스

• Exa Websets 문서

• Exa 대시보드

• MCP 프로토콜 사양

• Exa API 키 받기

개발

소스에서 빌드

git clone https://github.com/exa-labs/websets-mcp-server.git
cd websets-mcp-server
npm install
npm run build

프로젝트 구조

websets-mcp-server/
├── src/
│   ├── index.ts              # Main server setup
│   ├── types.ts              # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── config.ts         # API configuration
│   │   ├── createWebset.ts
│   │   ├── listWebsets.ts
│   │   ├── getWebset.ts
│   │   ├── updateWebset.ts
│   │   ├── deleteWebset.ts
│   │   ├── listItems.ts
│   │   ├── createEnrichment.ts
│   │   ├── createSearch.ts
│   │   ├── createWebhook.ts
│   │   ├── createImport.ts
│   │   └── ...
│   └── utils/
│       ├── api.ts            # Shared API client and error handling
│       └── logger.ts         # Logging utilities
├── package.json
└── tsconfig.json

라이선스

MIT

기여

기여를 환영합니다! github.com/exa-labs/websets-mcp-server에서 이슈나 PR을 열어주십시오.

지원

• 문서: docs.exa.ai

• Discord: Exa 커뮤니티 가입

• 이메일: support@exa.ai