Takuma-AI/perplexity-deep-research-mcp

Perplexity Deep Research MCP Server

An MCP (Model Context Protocol) server that enables Claude to perform exhaustive research using Perplexity's Sonar Deep Research model, providing lower hallucination rates through advanced search capabilities.

Why Perplexity Over OpenAI?

• Lower Hallucination Rates: Perplexity's models are specifically optimized for factual accuracy with built-in search
• Real-time Web Access: Always current information, not limited by training cutoffs
• Transparent Citations: Every claim is backed by verifiable sources
• Cost-Effective: More affordable for research tasks compared to OpenAI's Deep Research
• Specialized for Research: Purpose-built for comprehensive information gathering

Features

• Sonar Deep Research: Exhaustive multi-source research with reasoning
• Quick Research: Fast searches using Sonar and Sonar Pro models
• Adjustable Reasoning Effort: Control depth vs speed tradeoff (low/medium/high)
• Citation Tracking: Full source attribution for all information
• Token Usage Reporting: Track costs across input, output, reasoning, and search queries

Setup

1. Get Perplexity API Key

1. Sign up at Perplexity AI
2. Go to API settings: https://www.perplexity.ai/settings/api
3. Generate an API key

2. Install Dependencies

cd /Users/kate/Documents/Manual\ Library/Projects/takuma-os/tools/mcp/perplexity-deep-research
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

3. Configure API Key

Option A: Using credentials.json (recommended for development)

cp credentials.example.json credentials.json
# Edit credentials.json and add your API key

Option B: Using environment variable

export PERPLEXITY_API_KEY="your-api-key-here"

4. Test Connection

./venv/bin/python tests/test_connection.py

5. Connect to Claude Code

claude mcp add perplexity-deep-research \
  /Users/kate/Documents/Manual\ Library/Projects/takuma-os/tools/mcp/perplexity-deep-research/venv/bin/python \
  /Users/kate/Documents/Manual\ Library/Projects/takuma-os/tools/mcp/perplexity-deep-research/server.py

# Verify
claude mcp list

Available Tools

test_connection()

Test API connectivity and list available models.

start_research(query, reasoning_effort="medium")

Perform deep, exhaustive research on a topic.

• query: Your research question
• reasoning_effort: "low" (fast), "medium" (balanced), "high" (thorough)

research_to_file(query, output_path, reasoning_effort="medium", include_metadata=True, format="markdown")

NEW: Perform deep research and write results directly to a file.

• query: Your research question
• output_path: Full path where to save the research (e.g., /path/to/research.md)
• reasoning_effort: "low" (fast), "medium" (balanced), "high" (thorough)
• include_metadata: Whether to include citations and token usage in the file
• format: Output format - "markdown", "json", or "text"

get_result(id)

Retrieve results from a research session.

quick_research(query, model="sonar-pro")

Fast research for quick questions.

• model: "sonar" (basic) or "sonar-pro" (enhanced)

quick_research_to_file(query, output_path, model="sonar-pro", include_metadata=True, format="markdown")

NEW: Fast research written directly to a file.

• query: Your research question
• output_path: Full path where to save the research
• model: "sonar" (basic) or "sonar-pro" (enhanced)
• include_metadata: Whether to include citations in the file
• format: Output format - "markdown", "json", or "text"

Usage Examples

In Claude Code:

# Test the connection
mcp__perplexity-deep-research__test_connection()

# Quick research
mcp__perplexity-deep-research__quick_research("What is quantum computing?")

# Deep research with high reasoning
mcp__perplexity-deep-research__start_research(
    "Analyze the current state of AI safety research and key open problems",
    reasoning_effort="high"
)

# NEW: Deep research directly to file (no need for Claude to re-dictate)
mcp__perplexity-deep-research__research_to_file(
    query="Comprehensive analysis of financial therapy approaches",
    output_path="/Users/kate/Documents/research/financial-therapy.md",
    reasoning_effort="high",
    format="markdown"
)

# NEW: Quick research to file
mcp__perplexity-deep-research__quick_research_to_file(
    query="Latest developments in quantum computing",
    output_path="/Users/kate/Documents/research/quantum-update.json",
    format="json"
)

Cost Considerations

Perplexity pricing (per 1M tokens):

• Input: $2
• Output: $8
• Citations: $2
• Search Queries: $5 per 1K
• Reasoning: $3

Tips for cost management:

• Use quick_research() for simple queries
• Set reasoning_effort="low" for faster, cheaper results
• Deep research is best for complex, multi-faceted questions

How It Serves Takuma OS

This MCP server extends Takuma OS's knowledge capabilities by:

• Reducing Hallucinations: Grounded research for Labs product development
• Real-time Context: Current market data for Bespoke client work
• Knowledge Synthesis: Building the Knowledge library with verified information
• Decision Support: Factual basis for strategic choices

The server preserves Takuma OS philosophy:

• Ship Daily: Quick research enables rapid progress
• Find the Epicenter: Deep research reveals core insights
• Preserve Intent: Citations maintain source authenticity

Troubleshooting

API Key Issues

• Ensure key starts with pplx-
• Check key has not expired
• Verify billing is active on your Perplexity account

Timeout Errors

• Reduce reasoning_effort to "low" for faster results
• Break complex queries into smaller parts
• Use quick_research() for simple questions

No Results

• Check internet connectivity
• Verify Perplexity service status
• Try a simpler test query first

Development

To contribute or modify:

1. Create tests in tests/ directory (gitignored)
2. Test changes with ./venv/bin/python tests/test_connection.py
3. Ensure credentials are never committed

License

Part of Takuma OS - internal use only until open-sourced.