Perplexity MCP Server

A FastMCP server that integrates with Perplexity's API to provide web search and grounded AI answers.

Features

Three-Tier Research Workflow

1. search - Ground yourself first

   • Find relevant sources before asking questions

   • Returns URLs, titles, and snippets

   • Use this when you don't know about a topic

2. ask - Get AI answers (DEFAULT)

   • AI-synthesized answers with web grounding

   • Uses the sonar model (fast and cost-effective)

   • Includes citations and optional images/related questions

3. ask_more - Dig deeper

   • More comprehensive analysis for complex questions

   • Uses the sonar-pro model (more capable but pricier)

   • Use when ask doesn't provide sufficient depth

Prerequisites

• Python 3.10 or higher

• A Perplexity API key

• uv (recommended) or pip

Local Setup

1. Install Dependencies

Using uv (recommended):

uv pip install -e .

Or using pip:

pip install -e .

2. Configure API Key

Copy the example environment file:

cp .env.example .env

Edit .env and add your Perplexity API key:

PERPLEXITY_API_KEY=your_api_key_here

3. Run the Server

Test the server locally:

uv run fastmcp run server.py

Or with the fastmcp CLI:

fastmcp run server.py

4. Install in Claude Desktop

Install the server for use with Claude Desktop:

fastmcp install claude-code server.py

Or manually add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "perplexity": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/absolute/path/to/server.py"],
      "env": {
        "PERPLEXITY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cloud Deployment (FastMCP Cloud)

Deploy to fastmcp.cloud for easy hosting:

1. Push to GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/perplexity-mcp.git
git push -u origin main

2. Deploy on FastMCP Cloud

1. Visit fastmcp.cloud

2. Sign in with GitHub

3. Create a new project and connect your repo

4. Configure:

   • Entrypoint: server.py

   • Environment Variables: Add PERPLEXITY_API_KEY

5. Deploy!

Your server will be available at https://your-project-name.fastmcp.app/mcp

FastMCP Cloud automatically:

• ✅ Detects dependencies from pyproject.toml

• ✅ Deploys on every push to main

• ✅ Creates preview deployments for PRs

• ✅ Handles HTTP transport and authentication

Tool Usage Guide

Research Workflow Example

1. Don't know about a topic? → Use search()
   search("latest AI research papers on transformers")

2. Found sources? → Use ask() to understand
   ask("What are the key innovations in transformer models?")

3. Need more depth? → Use ask_more()
   ask_more("Explain the mathematical foundations of attention mechanisms in transformers")

Tool Parameters

search(query, max_results=10, recency=None, domain_filter=None)

• query: Search query string

• max_results: Number of results (default: 10)

• recency: Filter by time - "day", "week", "month", or "year"

• domain_filter: Include/exclude domains

  • Include: ["wikipedia.org", "github.com"]

  • Exclude: ["-reddit.com", "-pinterest.com"]

ask(query, reasoning_effort="medium", ...)

• query: Question to ask

• reasoning_effort: "low", "medium" (default), or "high"

• search_mode: "web" (default), "academic", or "sec"

• recency: Time filter

• domain_filter: Domain filter

• return_images: Include images (default: False)

• return_related_questions: Include follow-up questions (default: False)

ask_more(query, reasoning_effort="medium", ...)

Same parameters as ask(), but uses the more powerful sonar-pro model.

Cost Optimization

• Start with search: Free/cheap way to find sources

• Default to ask: Uses sonar (cost-effective)

• Escalate to ask_more: Only when needed (more expensive)

Development

Project Structure

perplexity-mcp/
├── server.py           # Main FastMCP server
├── pyproject.toml      # Dependencies
├── .env.example        # Environment template
└── README.md          # This file

Inspect the Server

See what FastMCP Cloud will see:

fastmcp inspect server.py

API Reference

This server uses two Perplexity API endpoints:

• Search API (/search) - Returns ranked search results

• Chat Completions API (/chat/completions) - Returns AI-generated answers

Supported models:

• sonar - Fast, cost-effective

• sonar-pro - More comprehensive

Troubleshooting

API Key Issues

If you get authentication errors:

1. Verify your API key at https://www.perplexity.ai/settings/api

2. Check that PERPLEXITY_API_KEY is set correctly

3. Make sure there are no extra spaces or quotes

Timeout Errors

If requests timeout:

• The default timeout is 30s for search, 60s for chat

• Complex questions may take longer

• Consider using reasoning_effort="low" for faster responses

Local Testing

Test individual tools:

uv run fastmcp dev server.py

This opens an interactive development interface.

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.

Links

• Perplexity API Docs

• FastMCP Docs

• FastMCP Cloud