Skip to content

Instantly share code, notes, and snippets.

@ahmed-pf

ahmed-pf/Setup Perplexity MCP Server on Raspberry Pi 4

Created November 29, 2025 15:39
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ahmed-pf/c7a742c508cbc8a0df3c50d92ab835cb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ahmed-pf/c7a742c508cbc8a0df3c50d92ab835cb to your computer and use it in GitHub Desktop.
Download ZIP
Setup Perplexity Search MCP server on Rpi4 4gb model , for access across LAN
Raw
Setup Perplexity MCP Server on Raspberry Pi 4
# Perplexity MCP Server Setup Guide for Raspberry Pi 4
Complete guide to set up a Perplexity MCP (Model Context Protocol) server on Raspberry Pi 4 (4GB) running Debian GNU/Linux 13 (trixie), accessible across your local network.
## System Requirements
- **Hardware**: Raspberry Pi 4 (4GB RAM)
- **OS**: Debian GNU/Linux 13 (trixie) - ARM64
- **Kernel**: Linux 6.12.47+rpt-rpi-v8 or later
- **Network**: Connected to LAN
## Prerequisites
Verify your system:
```bash
uname -a
# Expected: Linux rpi4 6.12.47+rpt-rpi-v8 #1 SMP PREEMPT Debian 1:6.12.47-1+rpt1 (2025-09-16) aarch64 GNU/Linux
lsb_release -a
# Expected: Debian GNU/Linux 13 (trixie)
```
---
## Step 1: Install Required Dependencies
### 1.1 Install Node.js (if not already installed)
```bash
# Check if Node.js is installed
node --version
# Should be v18+ (v25+ recommended)
# If not installed, install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
# Verify installation
node --version
npm --version
```
### 1.2 Install Python and pip
```bash
# Update package list
sudo apt update
# Install Python 3 and pip (usually pre-installed on Raspbian)
sudo apt install -y python3 python3-pip
# Verify installation
python3 --version
pip3 --version
```
### 1.3 Install mcp-streamablehttp-proxy
```bash
pip3 install mcp-streamablehttp-proxy
# Verify installation
which mcp-streamablehttp-proxy
```
---
## Step 2: Get Perplexity API Key
1. Visit [https://www.perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
2. Log in to your Perplexity account
3. Add a payment method (required for API access)
4. Purchase API credits (minimum $3)
5. Click **"Generate API Key"** or **"Create key"**
6. Copy the API key (starts with `pplx-`)
---
## Step 3: Set Up API Key in Environment
### 3.1 Add API Key to .bashrc (Permanent)
```bash
# Open .bashrc for editing
nano ~/.bashrc
# Add this line at the end (replace with your actual key)
export PERPLEXITY_API_KEY="pplx-YOUR-ACTUAL-KEY-HERE"
# Save and exit (Ctrl+X, then Y, then Enter)
# Reload .bashrc
source ~/.bashrc
# Verify the key is set
echo $PERPLEXITY_API_KEY
# Should display your API key
```
### 3.2 Alternative: Temporary Setup (Current Session Only)
```bash
export PERPLEXITY_API_KEY="pplx-YOUR-ACTUAL-KEY-HERE"
```
---
## Step 4: Start the MCP Server
### 4.1 Get Your Raspberry Pi's IP Address
```bash
hostname -I
# Example output: 192.168.0.31 (use this IP for LAN access)
```
### 4.2 Start the Server
```bash
mcp-streamablehttp-proxy --host 0.0.0.0 --port 8080 npx -y perplexity-mcp
```
**Expected Output:**
```
2025-11-29 17:49:06,628 - mcp_streamablehttp_proxy.server - INFO - Starting MCP stdio-to-HTTP proxy for: npx -y perplexity-mcp
INFO: Started server process [25112]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
```
**Server is now running!**
- Local access: `http://localhost:8080/mcp`
- LAN access: `http://YOUR_PI_IP:8080/mcp` (e.g., `http://192.168.0.31:8080/mcp`)
---
## Step 5: Test the Server from Another Machine on LAN
### 5.1 Test Connection (Initialize Session)
From any computer on your LAN, run:
```bash
curl -X POST http://192.168.0.31:8080/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "test",
"version": "1.0"
}
},
"id": 1
}'
```
**Expected Response:**
```json
{
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {}
},
"serverInfo": {
"name": "perplexity-server",
"version": "0.2.3"
}
},
"jsonrpc": "2.0",
"id": 1
}
```
**What to check:**
- Status code: `200 OK`
- Response includes `serverInfo` with `name: "perplexity-server"`
- Available tools: `search`, `reason`, `deep_research`
### 5.2 Test Search Functionality
First, initialize and capture the session ID from the response headers:
```bash
curl -X POST http://192.168.0.31:8080/mcp \
-H "Content-Type: application/json" \
-i \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "test",
"version": "1.0"
}
},
"id": 1
}'
```
Look for `Mcp-Session-Id` in the response headers (e.g., `58ae9209-0cc4-47bf-b64b-a6672124a407`).
Then test a search:
```bash
curl -X POST http://192.168.0.31:8080/mcp \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: YOUR-SESSION-ID-HERE" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "latest AI news today"
}
},
"id": 2
}'
```
**Expected Response:**
You should receive search results from Perplexity with citations and relevant information.
---
## Step 6: Integrate with Qwen CLI (or Any MCP Client)
### 6.1 Locate Qwen CLI Configuration File
Find your Qwen CLI settings file (usually `settings.json` or `config.json`):
```bash
# Common locations:
~/.config/qwen/settings.json
~/.qwen/settings.json
```
### 6.2 Add Perplexity MCP Server Configuration
Edit the configuration file and add the Perplexity server under `mcpServers`:
```json
{
"mcpServers": {
"perplexity": {
"command": "npx",
"args": [
"-y",
"@pyroprompts/mcp-stdio-to-streamable-http-adapter"
],
"env": {
"URI": "http://192.168.0.31:8080/mcp",
"MCP_NAME": "perplexity-remote"
}
}
}
}
```
**Important:** Replace `192.168.0.31` with your actual Raspberry Pi IP address.
### 6.3 Full Example with Multiple MCP Servers
If you have other MCP servers (like Tavily), your config might look like:
```json
{
"mcpServers": {
"tavily-remote": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-YOUR-KEY"
]
},
"perplexity": {
"command": "npx",
"args": [
"-y",
"@pyroprompts/mcp-stdio-to-streamable-http-adapter"
],
"env": {
"URI": "http://192.168.0.31:8080/mcp",
"MCP_NAME": "perplexity-remote"
}
}
}
}
```
### 6.4 Test Qwen CLI Integration
```bash
# Start Qwen CLI
qwen
# In the CLI, try using Perplexity tools
# Example: Ask a question that triggers the search tool
> What are the latest developments in AI?
```
The CLI should now use Perplexity's search capabilities to answer your questions.
---
## Available Tools
Your Perplexity MCP server provides **3 tools**:
1. **`search`** - Web search using Perplexity's Sonar model
- Fast, real-time web search with citations
2. **`reason`** - Advanced reasoning with sonar-reasoning-pro
- Deep analytical thinking for complex queries
3. **`deep_research`** - Deep research with sonar-deep-research
- Comprehensive research with multiple sources
---
## Troubleshooting
### Server Won't Start
**Error:** `mcp-streamablehttp-proxy: command not found`
```bash
# Solution: Reinstall the proxy
pip3 install --upgrade mcp-streamablehttp-proxy
```
**Error:** `npx: command not found`
```bash
# Solution: Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
```
### API Key Issues
**Error:** Authentication failed or invalid API key
```bash
# Verify your API key is set
echo $PERPLEXITY_API_KEY
# If empty, re-run Step 3
```
### Connection Issues from LAN
**Error:** `Connection refused` or `Timeout`
1. Check firewall settings:
```bash
sudo ufw status
# If active, allow port 8080
sudo ufw allow 8080
```
2. Verify the server is listening on 0.0.0.0:
```bash
ss -tlnp | grep 8080
# Should show: 0.0.0.0:8080
```
3. Ping your Pi from the client machine:
```bash
ping 192.168.0.31
```
### Session Expired Error
**Error:** `Session ID required` or `Session expired`
Solution: Sessions expire after inactivity. Re-initialize to get a new session ID.
---
## Performance Notes
- **Memory Usage**: ~100-200MB with idle server
- **CPU Usage**: Minimal when idle, spikes during searches
- **Network**: Requires stable internet connection for Perplexity API calls
- **Concurrent Sessions**: Supports multiple clients simultaneously
---
## Next Steps (Optional)
### Auto-Start on System Boot
Create a systemd service to run the server automatically:
```bash
sudo nano /etc/systemd/system/mcp-perplexity.service
```
Add:
```ini
[Unit]
Description=Perplexity MCP Server
After=network.target
[Service]
Type=simple
User=tom
Environment="PERPLEXITY_API_KEY=pplx-YOUR-KEY-HERE"
ExecStart=/usr/local/bin/mcp-streamablehttp-proxy --host 0.0.0.0 --port 8080 npx -y perplexity-mcp
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
Enable and start:
```bash
sudo systemctl daemon-reload
sudo systemctl enable mcp-perplexity
sudo systemctl start mcp-perplexity
sudo systemctl status mcp-perplexity
```
### Security Considerations
For production use:
- Use HTTPS with a reverse proxy (nginx/caddy)
- Implement authentication (API keys, OAuth)
- Restrict access by IP address
- Use a firewall to limit port 8080 access
---
## Additional Resources
- **Perplexity API Docs**: https://docs.perplexity.ai
- **MCP Protocol**: https://modelcontextprotocol.io
- **GitHub Issues**: https://github.com/perplexityai/modelcontextprotocol
---
## License
This guide is provided as-is for educational purposes. Perplexity API usage is subject to their terms of service.
---
**Last Updated:** November 29, 2025
**Tested On:** Raspberry Pi 4 (4GB), Debian GNU/Linux 13 (trixie), ARM64
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment