perplexity-mcp-server-perplexity-mcp

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Perplexity MCP Server

An MCP server that provides Perplexity AI web search capabilities to Claude, with automatic model selection, stateful filters, and 10 purpose-built tools.

<a href="https://glama.ai/mcp/servers/6qmvjay9z5">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/6qmvjay9z5/badge" alt="Perplexity Server MCP server" />
</a>

## Prerequisites

- Node.js v20 or higher
- A Perplexity API key — get one at <https://www.perplexity.ai/settings/api>
- Claude Desktop (or any MCP-compatible client)

## Installation

1. Clone this repository:

    ```bash
    git clone https://github.com/RossH121/perplexity-mcp.git
    cd perplexity-mcp
    ```

2. Install dependencies:

    ```bash
    npm install
    ```

3. Build the server:

    ```bash
    npm run build
    ```

## Configuration

Add the server to Claude's config file at `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "perplexity-server": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-mcp/build/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key-here",
        "PERPLEXITY_MODEL": "sonar-pro"
      }
    }
  }
}
```

Replace `/absolute/path/to` with the actual path to where you cloned the repository.

## Available Models

The server automatically selects the best model based on your query, but you can also set a default via `PERPLEXITY_MODEL`:

| Model | Best for |
|---|---|
| `sonar-deep-research` | Comprehensive reports, exhaustive multi-source research |
| `sonar-reasoning-pro` | Complex logic, math, chain-of-thought analysis |
| `sonar-pro` | General search, factual queries (default) |
| `sonar` | Quick, simple lookups |

For pricing and availability: <https://docs.perplexity.ai/guides/pricing>

## Tools

### `search` — AI-powered web search

The main search tool. Automatically selects the right model based on your query. Returns a synthesized answer with cited sources.

| Parameter | Options | Description |
|---|---|---|
| `query` | string | Your search query |
| `search_context_size` | `low` / `medium` / `high` | How much web context to retrieve. `low` is fastest/cheapest (default), `high` is most thorough |
| `search_type` | `fast` / `pro` / `auto` | Search engine tier (nested in `web_search_options`) |
| `reasoning_effort` | `minimal` / `low` / `medium` / `high` | Depth of reasoning for `sonar-deep-research` |
| `strip_thinking` | boolean | Remove `<think>...</think>` blocks from reasoning model responses |
| `search_mode` | `web` / `academic` / `sec` | `academic` prioritizes peer-reviewed papers; `sec` searches SEC filings |
| `search_after_date` / `search_before_date` | `MM/DD/YYYY` | Filter sources by publication date |
| `last_updated_after` / `last_updated_before` | `MM/DD/YYYY` | Filter sources by last-updated date |
| `search_language_filter` | `["en","de"]` | Restrict sources to languages (ISO 639-1) |
| `language_preference` | ISO 639-1 | Preferred response language |
| `disable_search` | boolean | Answer from training data only (no web search) |
| `enable_search_classifier` | boolean | Let a classifier decide whether to search |
| `return_images` | boolean | Append an Images section of result URLs |
| `image_domain_filter` / `image_format_filter` | string[] | Restrict images by domain or format |
| `return_related_questions` | boolean | Append follow-up question suggestions |
| `country` / `latitude` / `longitude` | — | Localize results via `user_location` |
| `stream_mode` | `full` / `concise` | Streaming event format for Pro Search |
| `show_cost` | boolean | Append a request-cost footer when available |
| `stream` | boolean | Enable streaming responses |

Examples:
- *"What's the latest on fusion energy?"* → auto-selects `sonar-pro`
- *"Deep research analysis of CRISPR gene editing advances"* → auto-selects `sonar-deep-research`
- *"Solve this logic puzzle step by step"* → auto-selects `sonar-reasoning-pro`

### `raw_search` — Raw ranked results (no LLM)

Returns ranked web results directly without AI synthesis. Faster and cheaper — useful for URL discovery, building source lists, or fact-checking pipelines.

| Parameter | Options | Description |
|---|---|---|
| `query` | string or string[] | Search query, or an array of queries run in one request |
| `max_results` | 1–20 | Number of results (default: 10) |
| `max_tokens` / `max_tokens_per_page` | number | Token budget overall / per result |
| `search_mode` | `web` / `academic` / `sec` | Source category |
| `search_type` | `web` / `people` | `people` routes to People Search |
| `recency` | `hour` / `day` / `week` / `month` / `year` | Time window filter |
| `search_after_date` / `search_before_date` | `MM/DD/YYYY` | Filter by publication date |
| `last_updated_after` / `last_updated_before` | `MM/DD/YYYY` | Filter by last-updated date |
| `search_language_filter` | `["en","de"]` | Restrict to languages (ISO 639-1) |
| `country` | ISO 3166 code | Localize results (e.g. `US`, `GB`) |

> Note: prior versions sent these params in camelCase, which the Search API silently ignored — so `max_results`, `recency`, `search_mode` and the date filters had no effect. This is fixed; they now take effect.

### `async_research` — Long-running deep research

Submit a `sonar-deep-research` job and poll it, instead of blocking on a synchronous call. Useful when research may exceed the 5-minute synchronous timeout. Jobs expire 7 days after creation.

| Parameter | Options | Description |
|---|---|---|
| `action` | `submit` / `status` / `list` | What to do |
| `query` | string | Research question (required for `submit`) |
| `request_id` | string | Job id from a prior `submit` (required for `status`) |
| `model` | Sonar model | Job model (default: `sonar-deep-research`) |
| `reasoning_effort` | `minimal` / `low` / `medium` / `high` | Reasoning depth |
| `search_mode` | `web` / `academic` / `sec` | Source category |
| `strip_thinking` | boolean | Strip `<think>` blocks from the completed result |

```
"Submit async research: comprehensive comparison of solid-state battery startups"
→ returns a request_id
"Check async research status for <request_id>"
```

### `agent` — Agentic loop with built-in tools

The Perplexity Agent API. Runs a multi-step agent that can call built-in tools and optionally a third-party model.

| Parameter | Options | Description |
|---|---|---|
| `input` | string | The task or question |
| `model` | e.g. `openai/gpt-4.1` | Provider-qualified model |
| `models` | string[] | Fallback chain (takes precedence over `model`) |
| `preset` | `fast-search` / `pro-search` / `deep-research` | Named preset instead of a model |
| `instructions` | string | System prompt |
| `max_steps` | 1–10 | Max agentic/tool steps |
| `max_output_tokens` | number | Max output tokens |
| `tools` | `web_search` / `fetch_url` | Built-in tools the agent may use |

### `embeddings` — Text embeddings

Generate embeddings via the Perplexity Embeddings API. Returns a compact summary (model, vector count, token usage) by default.

| Parameter | Options | Description |
|---|---|---|
| `input` | string or string[] | Text(s) to embed (max 512) |
| `model` | `pplx-embed-v1-0.6b` / `pplx-embed-v1-4b` | Embedding model (default: 0.6b) |
| `dimensions` | number | Output dimensions (Matryoshka) |
| `full` | boolean | Include raw base64-encoded vectors |

### `domain_filter` — Allowlist/blocklist domains

Restrict or exclude specific domains from search results. Filters persist across all subsequent searches until cleared.

- `action: "allow"` — restrict results to this domain (allowlist mode)
- `action: "block"` — exclude this domain from results (denylist mode)
- Maximum 20 domains; cannot mix allow and block in the same filter set

```
"Allow results only from arxiv.org and nature.com"
"Block pinterest.com and reddit.com from search results"
```

### `recency_filter` — Time window filter

Limit search results to a specific time period. Persists until changed.

Options: `hour`, `day`, `week`, `month`, `year`, `none`

```
"Set recency filter to week"
"Remove the recency filter"
```

### `clear_filters` — Reset all filters

Clears all domain and recency filters in one call.

### `list_filters` — View active filters

Shows currently active domain allowlist/blocklist and recency setting.

### `model_info` — View or override model selection

View available models and current selection, or manually force a specific model.

```
"Show model info"
"Set model to sonar-deep-research"
```

## Intelligent Model Selection

The server scores your query against keyword lists to automatically pick the right model:

- Research keywords (`deep research`, `comprehensive`, `in-depth`) → `sonar-deep-research`
- Reasoning keywords (`solve`, `logic`, `mathematical`, `figure out`) → `sonar-reasoning-pro`
- Simple keywords (`quick`, `brief`, `basic`) → `sonar`
- Everything else → `sonar-pro`

Each response shows which model was used and why. If a query strongly matches a model (score ≥ 2), it will override a manually set model.

## Example Workflows

**Time-sensitive research with domain filtering:**
1. `recency_filter` → `week`
2. `domain_filter` → allow `nature.com`, allow `arxiv.org`
3. `search` → *"Recent breakthroughs in quantum error correction"*

**Financial document research:**
1. `raw_search` with `search_mode: "sec"` → find relevant filings
2. `search` with `search_mode: "sec"` → synthesized analysis

**Academic literature review:**
1. `search` with `search_mode: "academic"`, `search_context_size: "high"` → comprehensive results from peer-reviewed sources

**Deep research with reasoning control:**
1. `search` with `reasoning_effort: "high"`, `strip_thinking: true` → thorough analysis without `<think>` blocks in the output

## Development

```bash
npm run build   # Compile TypeScript to build/
npm start       # Run the built server
```

Source is in `src/` — after editing, rebuild and restart Claude to load changes.

## License

MIT

Perplexity MCP Server

An MCP server that provides Perplexity AI web search capabilities to Claude, with automatic model selection, stateful filters, and 10 purpose-built tools.

Prerequisites

Node.js v20 or higher
A Perplexity API key — get one at https://www.perplexity.ai/settings/api
Claude Desktop (or any MCP-compatible client)

Installation

Clone this repository:

git clone https://github.com/RossH121/perplexity-mcp.git
cd perplexity-mcp

Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```

Configuration

Add the server to Claude's config file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity-server": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-mcp/build/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key-here",
        "PERPLEXITY_MODEL": "sonar-pro"
      }
    }
  }
}

Replace /absolute/path/to with the actual path to where you cloned the repository.

Available Models

The server automatically selects the best model based on your query, but you can also set a default via PERPLEXITY_MODEL:

Model	Best for
`sonar-deep-research`	Comprehensive reports, exhaustive multi-source research
`sonar-reasoning-pro`	Complex logic, math, chain-of-thought analysis
`sonar-pro`	General search, factual queries (default)
`sonar`	Quick, simple lookups

For pricing and availability: https://docs.perplexity.ai/guides/pricing

Tools

`search` — AI-powered web search

The main search tool. Automatically selects the right model based on your query. Returns a synthesized answer with cited sources.

Parameter	Options	Description
`query`	string	Your search query
`search_context_size`	`low` / `medium` / `high`	How much web context to retrieve. `low` is fastest/cheapest (default), `high` is most thorough
`search_type`	`fast` / `pro` / `auto`	Search engine tier (nested in `web_search_options`)
`reasoning_effort`	`minimal` / `low` / `medium` / `high`	Depth of reasoning for `sonar-deep-research`
`strip_thinking`	boolean	Remove `<think>...</think>` blocks from reasoning model responses
`search_mode`	`web` / `academic` / `sec`	`academic` prioritizes peer-reviewed papers; `sec` searches SEC filings
`search_after_date` / `search_before_date`	`MM/DD/YYYY`	Filter sources by publication date
`last_updated_after` / `last_updated_before`	`MM/DD/YYYY`	Filter sources by last-updated date
`search_language_filter`	`["en","de"]`	Restrict sources to languages (ISO 639-1)
`language_preference`	ISO 639-1	Preferred response language
`disable_search`	boolean	Answer from training data only (no web search)
`enable_search_classifier`	boolean	Let a classifier decide whether to search
`return_images`	boolean	Append an Images section of result URLs
`image_domain_filter` / `image_format_filter`	string[]	Restrict images by domain or format
`return_related_questions`	boolean	Append follow-up question suggestions
`country` / `latitude` / `longitude`	—	Localize results via `user_location`
`stream_mode`	`full` / `concise`	Streaming event format for Pro Search
`show_cost`	boolean	Append a request-cost footer when available
`stream`	boolean	Enable streaming responses

Examples:

"What's the latest on fusion energy?" → auto-selects sonar-pro
"Deep research analysis of CRISPR gene editing advances" → auto-selects sonar-deep-research
"Solve this logic puzzle step by step" → auto-selects sonar-reasoning-pro

`raw_search` — Raw ranked results (no LLM)

Returns ranked web results directly without AI synthesis. Faster and cheaper — useful for URL discovery, building source lists, or fact-checking pipelines.

Parameter	Options	Description
`query`	string or string[]	Search query, or an array of queries run in one request
`max_results`	1–20	Number of results (default: 10)
`max_tokens` / `max_tokens_per_page`	number	Token budget overall / per result
`search_mode`	`web` / `academic` / `sec`	Source category
`search_type`	`web` / `people`	`people` routes to People Search
`recency`	`hour` / `day` / `week` / `month` / `year`	Time window filter
`search_after_date` / `search_before_date`	`MM/DD/YYYY`	Filter by publication date
`last_updated_after` / `last_updated_before`	`MM/DD/YYYY`	Filter by last-updated date
`search_language_filter`	`["en","de"]`	Restrict to languages (ISO 639-1)
`country`	ISO 3166 code	Localize results (e.g. `US`, `GB`)

Note: prior versions sent these params in camelCase, which the Search API silently ignored — so max_results, recency, search_mode and the date filters had no effect. This is fixed; they now take effect.

`async_research` — Long-running deep research

Submit a sonar-deep-research job and poll it, instead of blocking on a synchronous call. Useful when research may exceed the 5-minute synchronous timeout. Jobs expire 7 days after creation.

Parameter	Options	Description
`action`	`submit` / `status` / `list`	What to do
`query`	string	Research question (required for `submit`)
`request_id`	string	Job id from a prior `submit` (required for `status`)
`model`	Sonar model	Job model (default: `sonar-deep-research`)
`reasoning_effort`	`minimal` / `low` / `medium` / `high`	Reasoning depth
`search_mode`	`web` / `academic` / `sec`	Source category
`strip_thinking`	boolean	Strip `<think>` blocks from the completed result

"Submit async research: comprehensive comparison of solid-state battery startups"
→ returns a request_id
"Check async research status for <request_id>"

`agent` — Agentic loop with built-in tools

The Perplexity Agent API. Runs a multi-step agent that can call built-in tools and optionally a third-party model.

Parameter	Options	Description
`input`	string	The task or question
`model`	e.g. `openai/gpt-4.1`	Provider-qualified model
`models`	string[]	Fallback chain (takes precedence over `model`)
`preset`	`fast-search` / `pro-search` / `deep-research`	Named preset instead of a model
`instructions`	string	System prompt
`max_steps`	1–10	Max agentic/tool steps
`max_output_tokens`	number	Max output tokens
`tools`	`web_search` / `fetch_url`	Built-in tools the agent may use

`embeddings` — Text embeddings

Generate embeddings via the Perplexity Embeddings API. Returns a compact summary (model, vector count, token usage) by default.

Parameter	Options	Description
`input`	string or string[]	Text(s) to embed (max 512)
`model`	`pplx-embed-v1-0.6b` / `pplx-embed-v1-4b`	Embedding model (default: 0.6b)
`dimensions`	number	Output dimensions (Matryoshka)
`full`	boolean	Include raw base64-encoded vectors

`domain_filter` — Allowlist/blocklist domains

Restrict or exclude specific domains from search results. Filters persist across all subsequent searches until cleared.

action: "allow" — restrict results to this domain (allowlist mode)
action: "block" — exclude this domain from results (denylist mode)
Maximum 20 domains; cannot mix allow and block in the same filter set

"Allow results only from arxiv.org and nature.com"
"Block pinterest.com and reddit.com from search results"

`recency_filter` — Time window filter

Limit search results to a specific time period. Persists until changed.

Options: hour, day, week, month, year, none

"Set recency filter to week"
"Remove the recency filter"

`clear_filters` — Reset all filters

Clears all domain and recency filters in one call.

`list_filters` — View active filters

Shows currently active domain allowlist/blocklist and recency setting.

`model_info` — View or override model selection

View available models and current selection, or manually force a specific model.

"Show model info"
"Set model to sonar-deep-research"

Intelligent Model Selection

The server scores your query against keyword lists to automatically pick the right model:

Research keywords (deep research, comprehensive, in-depth) → sonar-deep-research
Reasoning keywords (solve, logic, mathematical, figure out) → sonar-reasoning-pro
Simple keywords (quick, brief, basic) → sonar
Everything else → sonar-pro

Each response shows which model was used and why. If a query strongly matches a model (score ≥ 2), it will override a manually set model.

Example Workflows

Time-sensitive research with domain filtering:

recency_filter → week
domain_filter → allow nature.com, allow arxiv.org
search → "Recent breakthroughs in quantum error correction"

Financial document research:

raw_search with search_mode: "sec" → find relevant filings
search with search_mode: "sec" → synthesized analysis

Academic literature review:

search with search_mode: "academic", search_context_size: "high" → comprehensive results from peer-reviewed sources

Deep research with reasoning control:

search with reasoning_effort: "high", strip_thinking: true → thorough analysis without <think> blocks in the output

Development

npm run build   # Compile TypeScript to build/
npm start       # Run the built server

Source is in src/ — after editing, rebuild and restart Claude to load changes.

License

MIT

perplexity-mcp-server-perplexity-mcp

原始内容

Perplexity MCP Server

Prerequisites

Installation

Configuration

Available Models

Tools

search — AI-powered web search

raw_search — Raw ranked results (no LLM)

async_research — Long-running deep research

agent — Agentic loop with built-in tools

embeddings — Text embeddings

domain_filter — Allowlist/blocklist domains

recency_filter — Time window filter

clear_filters — Reset all filters

list_filters — View active filters

model_info — View or override model selection