mcp-perplexity

English | ภาษาไทย

A ready-to-run Docker setup of the official Perplexity MCP server that gives AI agents and assistants web search, question answering with citations, step-by-step reasoning and deep research, powered by Perplexity.

Any MCP client that supports streamable HTTP can use it, for example Claude Code, Claude Desktop, VS Code, Cursor or your own agent. The Perplexity API key stays in the container, and every call is logged with its tokens, time and cost, so you always know what your agent spent. You do not need Node.js on your machine.

This project packages the official Perplexity MCP server; it does not reimplement it. The server is developed by Perplexity AI under the MIT license. This project is not an official Perplexity product.

• What you get

• Tools

• How it works

• Quick start (Docker)

• Running without Docker

• Connecting an MCP client

• Calling it directly (JSON)

• Turning tools on and off

• Usage and cost data

• Configuration reference

• Security

• Troubleshooting

• Development

What you get

• Four tools, from cheap to thorough. Raw search results, quick answers, reasoned answers and full research reports. Pick the depth you need per task.

• Answers with citations. The answering tools return text with reference numbers such as [2][3] and a list of source URLs.

• Only the tools you want. Each tool has its own switch in .env. The example file turns on only perplexity_search, the fastest and cheapest. A tool that is off disappears from the client's tool list.

• Token, time and cost log. Perplexity reports tokens and cost with every answer, but the official server drops them. This project records them, one JSON line per call, at GET /usage. Numbers only, never the question or the answer.

• The official server, unchanged. Two small hook files are loaded before it with node --import. Updating to a new Perplexity release means changing one version number.

• Locked dependencies. package-lock.json pins the server and every library, so every build is the same.

Related MCP server: qsearch

Tools

All tools are read-only. Every call is billed to your PERPLEXITY_API_KEY. See current prices on the Perplexity pricing page.

You do not call the tools yourself: you ask your agent in plain language and it picks the tool and fills in the parameters. To steer it, say what you want, e.g. "quick web search" or "do deep research on…", because cost and time differ a lot between tools.

perplexity_search

Example requests to an agent: "Find the GitHub link of LightRAG", "News about EU AI policy this week, only from europa.eu".

Best when you want original sources, or when your agent should read and summarize by itself.

perplexity_ask and perplexity_reason

Example requests: "What is LightRAG? Keep it short.", "Compare the energy use of the three largest data-center regions."

The answer is text with reference numbers such as [2][3] and the list of source URLs at the end.

perplexity_research

Example request: "Do deep research on how governments use retrieval-augmented generation and write a report."

Takes only messages. It can run for several minutes and costs the most, so use it when you really need a report from many sources, and give your client a long enough timeout (see Connecting an MCP client).

How it works

MCP client / agent ──POST /mcp──▶ mcp-perplexity (container, port 8080)
                                    ① checks the Host header against ALLOWED_HOSTS (HTTP 421 if not listed)
                                    ② tools-hook.mjs has removed the tools that are switched off
                                    ③ the tool calls https://api.perplexity.ai with PERPLEXITY_API_KEY
                                    ④ usage-hook.mjs reads a copy of the answer and logs tokens, time and cost
                  ◀── the answer goes back to the client unchanged

usage/*.jsonl ──GET /usage (port 8081, docker network only)──▶ your spreadsheet, dashboard or research

The server keeps no state and has no database. The only volume holds the usage log.

Quick start (Docker)

You need Docker with Docker Compose, an internet connection for the first build (to download the Node image and npm packages), and a Perplexity API key from console.perplexity.ai.

1. Get the code

git clone https://github.com/chacharin/mcp-perplexity.git

cd mcp-perplexity

2. Create the docker network (once per machine). Containers on this network, such as an agent running in Docker, reach the server by name. Skip this step if the network already exists.

docker network create agent_network

3. Create .env and put your key in it

cp .env.example .env

Open .env and replace the example value of PERPLEXITY_API_KEY with your key. Only perplexity_search is on; to use the other tools, set their ENABLE_PERPLEXITY_… lines to true (see Turning tools on and off).

4. Start the server

docker compose up -d --build

5. Check it

curl http://127.0.0.1:8803/health

{"status":"ok", …} means the server is running. It does not check the key: a wrong key shows up as 401 Unauthorized on the first tool call.

The MCP endpoint is now http://localhost:8803/mcp on this machine, and http://mcp-perplexity:8080/mcp from other containers on agent_network.

After editing .env, run docker compose up -d again (no rebuild needed). To stop the server, run docker compose down. The usage log is kept in the usage volume.

Running without Docker

You need Node.js 22 or newer.

npm ci --omit=dev

Add these lines to .env so the server listens on port 8803 of this machine only and keeps its log in the project folder:

BIND_ADDRESS=127.0.0.1
PORT=8803
ALLOWED_HOSTS=localhost:8803,127.0.0.1:8803
USAGE_DIR=./usage

node --env-file=.env --import ./tools-hook.mjs --import ./usage-hook.mjs node_modules/@perplexity-ai/mcp-server/dist/http.js

The usage endpoints are then at http://127.0.0.1:8081/health and http://127.0.0.1:8081/usage.

Connecting an MCP client

The server speaks streamable HTTP. Use the URL that your client can reach:

Set a long timeout. perplexity_research can take several minutes. If the client gives up first, it reports a failure while Perplexity keeps working and still bills the call. 600 seconds is a safe value.

Claude Code

claude mcp add --transport http perplexity http://localhost:8803/mcp

Claude Desktop (claude_desktop_config.json, through the mcp-remote bridge; needs Node.js)

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8803/mcp"]
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "perplexity": { "type": "http", "url": "http://localhost:8803/mcp" }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "perplexity": { "url": "http://localhost:8803/mcp" }
  }
}

Hermes Agent (config.yaml)

mcp_servers:
  perplexity:
    url: http://mcp-perplexity:8080/mcp
    timeout: 600

Other clients: use the URL above with the streamable HTTP transport. A client that runs inside a web page (or MCP Inspector in Direct mode) also needs its page address in ALLOWED_ORIGINS.

Try it without an agent using MCP Inspector (needs Node.js):

npx @modelcontextprotocol/inspector

In the page that opens, choose Transport = Streamable HTTP, URL = http://localhost:8803/mcp, Connection type = Via Proxy, press Connect, then open Tools and run perplexity_search.

A tip for your agent's instructions. Tell it when to use which tool, for example: "Use perplexity_search for facts and sources. Use perplexity_research only when I ask for a report. Cite every URL you use."

Calling it directly (JSON)

The server has these routes:

Every request to /mcp needs these two headers, and the Host it uses must be in ALLOWED_HOSTS:

Content-Type: application/json
Accept: application/json, text/event-stream

The server answers with plain JSON. Each tool's text is in result.content[0].text, and again in result.structuredContent (key results for perplexity_search, response for the other tools).

List the tools (free)

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

Only tools that are switched on are listed.

Search

{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {
  "name": "perplexity_search",
  "arguments": {"query": "LightRAG HKUDS GitHub", "max_results": 2}
}}

Reply (shortened):

{"jsonrpc": "2.0", "id": 2, "result": {
  "content": [{"type": "text",
    "text": "Found 2 search results:\n\n1. **[EMNLP2025] LightRAG: Simple and Fast Retrieval- ...**\n   URL: https://github.com/hkuds/lightrag\n   GitHub - HKUDS/LightRAG: … LightRAG is a lightweight knowledge-graph RAG framework …\n   Date: …\n\n2. …"}],
  "structuredContent": {"results": "Found 2 search results: …"}
}}

Ask (perplexity_ask, perplexity_reason and perplexity_research take the same request)

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {
  "name": "perplexity_ask",
  "arguments": {
    "messages": [{"role": "user", "content": "What is LightRAG? Answer in two sentences."}],
    "search_context_size": "low"
  }
}}

Reply (shortened):

{"jsonrpc": "2.0", "id": 3, "result": {
  "content": [{"type": "text",
    "text": "LightRAG is a RAG framework that builds a knowledge graph from documents and combines graph and vector retrieval …[2][3]\n\nCitations:\n[1] …\n[2] https://arxiv.org/html/2410.05779v1\n[3] https://github.com/hkuds/lightrag"}],
  "structuredContent": {"response": "LightRAG is a RAG framework … Citations: …"}
}}

With curl (this calls Perplexity and is billed; use "method":"tools/list" without params to test for free)

curl http://127.0.0.1:8803/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"perplexity_search","arguments":{"query":"LightRAG HKUDS GitHub","max_results":2}}}'

On Windows, curl may turn non-English text typed on the command line into ?. Save the request as a UTF-8 file such as request.json and send it with -d @request.json.

Turning tools on and off

Each tool has its own line in .env. true/false, 1/0, yes/no and on/off all work. The example file has:

ENABLE_PERPLEXITY_SEARCH=true
ENABLE_PERPLEXITY_ASK=false
ENABLE_PERPLEXITY_REASON=false
ENABLE_PERPLEXITY_RESEARCH=false

• A tool that is off is not in the tool list, so the agent never sees it, its description costs no tokens, and a direct call is refused. This works the same for every client.

• A line that is missing counts as true, so an older .env without these lines keeps all four tools.

• A value that cannot be read, such as maybe, keeps the tool on and is reported in the log and at GET :8081/health.

• Apply a change with docker compose up -d, then reconnect or restart the client. Clients read the tool list when they connect.

Check the switches at http://mcp-perplexity:8081/health (from the docker network):

{"ok": true, "tools": {"perplexity_search": true, "perplexity_ask": false, "…": "…"}, "problems": [], "…": "…"}

Usage and cost data

The log is JSON Lines in the usage volume, one file per day (usage-YYYY-MM-DD.jsonl), in the harness-usage/1 schema. It holds numbers only: no questions, answers or search terms.

Read it from a container on the docker network, for example:

docker run --rm --network agent_network curlimages/curl -s http://mcp-perplexity:8081/usage

Example record (shortened) after one perplexity_ask call:

{"kind": "llm_call", "tool": "perplexity_ask", "model": "openai/gpt-6-luna", "provider": "perplexity",
 "duration_s": 2.342, "ttfb_s": 0.803, "input_tokens": 3, "cache_write_tokens": 5705, "output_tokens": 16,
 "total_tokens": 5724, "cost_usd": 0.00172, "status": "ok",
 "detail": {"endpoint": "v1/agent", "preset": "fast", "search_queries": 1, "search_results": 5,
            "usage_raw": {"cost": {"tool_calls_cost": 0.001, "total_cost": 0.00172, "…": "…"}}}}

• detail.usage_raw is the full usage report from Perplexity. The web-search part (tool_calls_cost) is often larger than the token cost.

• The hook only sees direct calls to Perplexity. With PERPLEXITY_PROXY set, the official server takes another path and no usage is recorded.

• Turn logging off with USAGE_LOG=false.

Configuration reference

All settings live in .env. Each one is also explained in .env.example. After a change, run docker compose up -d.

Security

• The MCP endpoint has no login. Anyone who can reach the port can spend your Perplexity balance. The default (PUBLISH_ADDR=0.0.0.0) lets other machines connect. If you don't need that, set PUBLISH_ADDR=127.0.0.1; agents on the docker network still work.

• Set a spending limit for the key at console.perplexity.ai to cap the damage of misuse.

• ALLOWED_HOSTS blocks DNS-rebinding attacks from web browsers. List only the names you really use. It does not stop direct calls from your network.

• Never commit .env. It is in .gitignore. The key stays in the container; agents never see it.

• The usage port (8081) is not published outside Docker and holds no questions or answers. Set USAGE_TOKEN to require a token.

• The container runs as a non-root user.

• Search results and answers come from the open web. Tell your agent to treat them as information, not as instructions.

Troubleshooting

See the server's own log with docker compose logs -f. Set PERPLEXITY_LOG_LEVEL=DEBUG for more detail.

Development

The official server is used as it is. This project's own code is two hook files loaded before it with node --import.

Run the tests (no Node.js needed on your machine):

docker run --rm -v "$PWD:/w" -w /w node:22.23.3-alpine3.24 sh -c "npm ci && npm test"

Updating the Perplexity MCP server

docker run --rm -v "$PWD:/w" -w /w node:22.23.3-alpine3.24 sh -c "npm install --package-lock-only --no-audit --no-fund @perplexity-ai/mcp-server@<new-version>"

docker compose up -d --build

Run the tests, then commit the changed package.json and package-lock.json. In PowerShell, write ${PWD} instead of $PWD.

License

MIT © 2026 Chacharin Lertyosbordin. The Perplexity MCP server is © Perplexity AI under the MIT license (source). Perplexity is a trademark of its owner. This project is not affiliated with Perplexity AI.