Perplexity

공식

Perplexity의 Sonar API에 연결하여 대화형 AI에서 실시간 웹 전체 연구를 가능하게 하는 MCP 서버입니다.

GitHub
2.4k

Perplexity MCP(으)로 무엇을 할 수 있나요?

  • 실시간 웹 검색 — perplexity_search를 통해 최신 정보를 요청할 수 있으며, 선택적으로 최신성 필터와 도메인 제한을 적용할 수 있습니다.
  • 실시간 소스를 활용한 빠른 Q&A — perplexity_ask를 사용하여 실시간 웹 검색에 기반한 대화형 답변을 얻을 수 있습니다.
  • 심층 연구 보고서 — perplexity_research를 통해 장기 실행 작업의 진행 상황을 스트리밍하는 철저한 다단계 분석을 요청할 수 있습니다.
  • 복잡한 추론 작업 — perplexity_reason을 활용하여 고급 문제 해결 및 분석 작업을 수행할 수 있습니다.
  • 맞춤형 배포 옵션 — 서버를 로컬, Docker, 또는 구성 가능한 프록시 및 보안 설정을 갖춘 자체 호스팅 HTTP 서비스로 실행할 수 있습니다.

문서

Perplexity API 플랫폼 MCP 서버

Install in Cursor   Install in VS Code   Add to Kiro   npm version

Perplexity API 플랫폼의 공식 MCP 서버 구현으로, Agent API와 Search API를 통해 AI 어시스턴트에게 실시간 웹 검색, 추론, 리서치 기능을 제공합니다.

원격 MCP 서버

원격 MCP 서버는 Perplexity가 호스팅하며 시작하기 가장 쉬운 방법입니다: 동일한 도구를 제공하며 설치하거나 업데이트할 필요가 없습니다. 이 페이지 상단의 Cursor 및 VS Code 버튼을 클릭하면 한 번에 연결됩니다. MCP 클라이언트가 아직 원격 서버를 지원하지 않는 경우, 아래의 로컬 서버 설정으로 건너뛰세요. Perplexity API 키로 Streamable HTTP를 통해 연결하세요:

https://api.perplexity.ai/mcp

Claude Code의 경우:

claude mcp add --transport http perplexity https://api.perplexity.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"

수동 Cursor/VS Code 구성, Anthropic API 사용, 기타 클라이언트 설정에 대한 자세한 내용은 MCP 통합 문서를 참조하세요.

로컬 MCP 서버

API 키 받기

  1. API 포털에서 Perplexity API 키를 받으세요
  2. 아래 구성에서 your_key_here를 본인의 API 키로 교체하세요
  3. (선택 사항) 타임아웃 설정: PERPLEXITY_TIMEOUT_MS=600000 (기본값: 5분)
  4. (선택 사항) 사용자 지정 기본 URL 설정: PERPLEXITY_BASE_URL=https://your-custom-url.com (기본값: https://api.perplexity.ai)
  5. (선택 사항) 로그 레벨 설정: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (기본값: ERROR)

Claude Code

claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

또는 플러그인으로 설치:

export PERPLEXITY_API_KEY="your_key_here"
claude
# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
# Then run: /plugin install perplexity

Codex

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

기타 MCP 클라이언트

대부분의 클라이언트는 클라이언트 구성에서 동일한 mcpServers 래퍼를 사용하여 수동으로 구성할 수 있습니다 (Cursor에 표시된 대로). 클라이언트의 스키마가 다른 경우 정확한 래퍼 형식에 대해 해당 문서를 확인하세요.

수동 설정의 경우, 이 클라이언트들은 모두 동일한 mcpServers 구조를 사용합니다:

클라이언트구성 파일
Cursor~/.cursor/mcp.json
Claude Desktopclaude_desktop_config.json
Kiro.kiro/settings/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
VS Code.vscode/mcp.json
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

프록시 설정 (기업 네트워크용)

회사에서 이 서버를 실행하는 경우—특히 회사 방화벽이나 프록시 뒤에서—프로그램이 네트워크의 프록시를 통해 인터넷 트래픽을 보내는 방법을 알려줘야 할 수 있습니다. 다음 단계를 따르세요:

1. 프록시 정보 확인

  • IT 부서에 HTTPS 프록시 주소와 포트를 문의하세요.
  • 사용자 이름과 비밀번호도 필요할 수 있습니다.

2. 프록시 환경 변수 설정

Perplexity MCP의 가장 쉽고 안정적인 방법은 PERPLEXITY_PROXY를 사용하는 것입니다. 예:

export PERPLEXITY_PROXY=https://your-proxy-host:8080

프록시에 사용자 이름과 비밀번호가 필요한 경우:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

3. 대안: 표준 환경 변수

표준 변수를 선호하는 경우, HTTPS_PROXY 및 HTTP_PROXY를 지원합니다.

[!NOTE] 서버는 다음 순서로 프록시 설정을 확인합니다: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. 설정된 값이 없으면 인터넷에 직접 연결합니다. URL에는 https://가 포함되어야 합니다. 일반적인 포트는 8080, 3128, 80입니다.

자체 호스팅 HTTP 모드

클라우드 또는 공유 배포의 경우 HTTP 모드에서 서버를 실행하세요.

환경 변수

변수설명기본값
PERPLEXITY_API_KEYPerplexity API 키필수
PERPLEXITY_BASE_URLAPI 요청용 사용자 지정 기본 URLhttps://api.perplexity.ai
PORTHTTP 서버 포트8080
BIND_ADDRESS바인딩할 네트워크 인터페이스. 기본값은 루프백. 모든 인터페이스에 노출하려면 0.0.0.0로 설정.127.0.0.1
ALLOWED_ORIGINSCORS 오리진 (쉼표로 구분). 기본값은 비어 있음 (교차 오리진 브라우저 요청 없음). 명시적 허용 목록 (예: https://app.example.com) 또는 모든 오리진 허용 시 *로 설정.(비어 있음)
ALLOWED_HOSTS허용할 추가 Host 헤더 값 (쉼표로 구분). PORT의 루프백 호스트는 항상 허용됩니다. 0.0.0.0에 바인딩할 때 공개 호스트 이름을 추가하세요.(루프백만)

Docker

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Node.js

export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http

서버는 http://localhost:8080/mcp에서 접근할 수 있습니다

사용 가능한 도구

perplexity_search

Perplexity Search API를 사용한 직접 웹 검색. 메타데이터와 함께 순위가 매겨진 검색 결과를 반환하며, 최신 정보를 찾는 데 적합합니다. 최신성 필터(search_recency_filter) 및 도메인 제한(search_domain_filter)을 지원합니다.

perplexity_ask

실시간 웹 검색을 지원하는 범용 대화형 AI로, Agent API fast 프리셋을 기반으로 합니다. 빠른 질문과 일상적인 검색에 적합합니다.

perplexity_research

Agent API high 프리셋을 기반으로 하는 심층적이고 포괄적인 리서치. 철저한 분석과 상세한 보고서에 이상적입니다. 실행에 수 분이 걸릴 수 있습니다; 서버는 실행을 스트리밍하고 요청하는 클라이언트에게 진행 상황을 보고합니다.

perplexity_reason

Agent API medium 프리셋을 기반으로 하는 고급 추론 및 문제 해결. 복잡한 분석 작업에 적합합니다.

[!NOTE] 프리셋은 Perplexity가 시간이 지남에 따라 조정하는 관리형 구성(모델, 검색 설정, 단계 예산)입니다; 프리셋 가이드를 참조하세요. 이 서버의 이전 버전은 레거시 sonar-pro, sonar-reasoning-pro, sonar-deep-research 모델을 호출하고 strip_thinking / reasoning_effort 매개변수를 허용했습니다. 해당 매개변수는 더 이상 도구 스키마의 일부가 아니며 전송 시 무시됩니다; Agent API는 <think> 태그를 생성하지 않습니다.

라이브러리로 사용

패키지는 자체 Node 프로세스에 포함하기 위한 서버 팩토리도 내보냅니다:

import { createPerplexityServer } from "@perplexity-ai/mcp-server";

// Single-tenant: reads PERPLEXITY_API_KEY from the environment.
const server = createPerplexityServer("my-service");

// Multi-tenant hosts resolve the key per call instead. When a provider is
// set, the environment variable is never consulted, and a provider that
// returns no key fails the call rather than falling back.
const tenantServer = createPerplexityServer("my-service", {
  apiKey: () => currentRequestApiKey,
});

반환된 서버를 모든 MCP 전송(stdio, streamable HTTP, in-memory)에 마운트하세요.

문제 해결

  • API 키 문제: PERPLEXITY_API_KEY가 올바르게 설정되었는지 확인하세요
  • 연결 오류: 인터넷 연결과 API 키 유효성을 확인하세요
  • 도구를 찾을 수 없음: 패키지가 설치되었고 명령 경로가 올바른지 확인하세요
  • 타임아웃 오류: 매우 긴 리서치 쿼리의 경우 PERPLEXITY_TIMEOUT_MS를 더 높은 값으로 설정하세요
  • 프록시 문제: PERPLEXITY_PROXY 또는 HTTPS_PROXY 설정을 확인하고 api.perplexity.ai가 방화벽에 의해 차단되지 않았는지 확인하세요.
  • EOF / 초기화 오류: 일부 엄격한 MCP 클라이언트는 npx가 설치 메시지를 stdout에 쓰기 때문에 실패합니다. 이 출력을 억제하려면 npx -yq 대신 npx -y를 사용하세요.

지원이 필요한 경우 community.perplexity.ai를 방문하거나 이슈를 등록하세요.