Perplexity's MCP server publishes a Docker port its own container binds to loopback
The official MCP server implementation for the Perplexity API Platform
At a glance
- What is it?
- The official MCP server for the Perplexity API Platform, with four entry points, two deployment modes and allowlists that default closed, packaged at version 1.3.0 on npm with no GitHub releases at all. MIT licensed, last commit 2026-09-25.
- Who is it for?
- This is the server to reach for if you want Perplexity's search and Agent API inside an MCP client, and the remote endpoint at api.perplexity.ai/mcp removes the installation question entirely. For a local install, read the env table before the Docker quickstart, because the two disagree: the run command publishes port 8080 while the container binds 127.0.0.1 by default, and the host allowlist needs your public hostname once you bind 0.0.0.0.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 25 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- perplexityai/modelcontextprotocol2,632 ★ · +87
| Repository | 2026-09-30 | 2026-11-15 |
|---|---|---|
| perplexityai/modelcontextprotocol | 2.5k | 2.6k |
87 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The documented container command publishes a port nothing listens on
The Docker quickstart is two lines:
docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-serverThe image it builds has a fixed entry point, `ENTRYPOINT ["node", "dist/http.js"]`, so the container always starts in HTTP mode and always exposes 8080. The variable table further down the same page says `BIND_ADDRESS` defaults to `127.0.0.1` and that setting it to `0.0.0.0` is what exposes the server on all interfaces.
Those two statements collide. A port mapping forwards to the container's network interface, and the server is listening on loopback inside the container, so the published 8080 reaches nothing. The page says as much in its own words further up: the host-side default is loopback and exposure is governed there. The quickstart just does not carry the two settings that would make it work, a bind address of 0.0.0.0 and a hostname added to `ALLOWED_HOSTS`.
The project names its own escape hatch UNSAFE, twice
The manifest carries two scripts whose names include the word in capitals:
"start:http:UNSAFE-public": "BIND_ADDRESS=0.0.0.0 ALLOWED_ORIGINS=* node dist/http.js",
"dev:http:UNSAFE-public": "BIND_ADDRESS=0.0.0.0 ALLOWED_ORIGINS=* tsx src/http.ts"One is the production path and one is the TypeScript source run through tsx. Both set the bind address to every interface and the origin allowlist to a wildcard in the same breath, which is exactly the combination the environment table describes as the permissive option.
The naming is the point. Rather than documenting a public deployment mode and warning about it in prose, the project puts the warning in the command you would type. Anyone reaching for HTTP mode on a shared host has to either type those two variables deliberately or copy one of these scripts, and either way the word is on the screen at the moment the decision is made.
Four entry points, three of which are not the library
The manifest points at three different compiled files for three different purposes. `main` is `dist/server.js` with types at `dist/server.d.ts`, which is what an importing program resolves. `bin` is `dist/index.js`, exposed as the `perplexity-mcp` command. And `start` runs `node dist/index.js` as well, so the installed binary and the default start script are the same file.
HTTP mode is a fourth path, `dist/http.js`, reached through `start:http` and through the container entry point. The development scripts mirror the same split with `tsx`: `dev` for `src/index.ts` and `dev:http` for `src/http.ts`.
So there are two servers and one library surface, and the choice between them is which file you launch. The stdio path is the default and needs no ports, no origins and no host allowlist. The HTTP path is what the shared and cloud deployment instructions use, and it is the one that brings the security configuration with it.
The build emits test files and the manifest excludes them by name
The `files` array is worth reading closely, because it is a list of things being kept out as much as things being shipped:
"files": [
"dist/*.js",
"dist/*.d.ts",
"!dist/*.test.js",
"!dist/*.test.d.ts",
"!dist/vitest.config.js",
"!dist/vitest.config.d.ts",
"README.md",
".claude-plugin"
]Two globs bring in everything the TypeScript build emitted into `dist/`, and four negated patterns then remove the test files and the vitest configuration that the same build put there. That is the shape of a project whose compiler emits tests alongside sources, which is also why the build script is `tsc && shx chmod +x dist/*.js` and needs a shell helper to mark the output executable.
The last entry is not a file at all but a directory, `.claude-plugin`, and it is what lets the repository install as an Agent Plugin. The tree also carries `plugin.json`, `server.json`, `smithery.yaml` and a root `mcp.json`, so the same server is described four separate times for four different registries.
The image compiles on a pinned Node and runs on a floating one
The Dockerfile has two stages and the Node tags are not the same in both. The builder is `node:22.12-alpine`, the release stage is `node:22-alpine`, so the compiler runs against a fixed patch level and the output runs against whatever the 22 tag currently points at.
The install commands differ too. The builder runs `npm install --ignore-scripts` with a cache mount on the npm directory, then copies `src/` and runs `npm run build`. The release stage copies `dist/`, `package.json` and `package-lock.json` out of the builder, sets `NODE_ENV=production`, and runs `npm ci --ignore-scripts --omit=dev`. So the image never compiles anything itself; it copies compiled output and installs production dependencies against the lockfile.
`--ignore-scripts` appears in both stages. That is consistent with the manifest, whose `prepare` script runs the build, and it means neither install can trigger a compile as a side effect. The build has to happen in the builder stage, and it does.
Proxy settings resolve in a stated order, with credentials in the URL
For anyone behind a company proxy, the server reads three variables and it says which wins: `PERPLEXITY_PROXY` first, then `HTTPS_PROXY`, then `HTTP_PROXY`, and with none of them set it connects to the internet directly. Two constraints follow from the same note, that URLs must include `https://` and that the usual ports are 8080, 3128 and 80.
Credentials go in the URL itself, in the form `https://username:password@your-proxy-host:8080`. That is the form the documentation gives for a proxy that needs authentication, and it is worth noticing that the password then sits in an environment variable and in the shell history of whatever exported it.
The variable that matters more for day-to-day use is the timeout. `PERPLEXITY_TIMEOUT_MS` defaults to five minutes, and the documented override is 600000, which is the same number written out. A reasoning call on the Agent API can take a while, and this is the setting that decides whether a slow answer arrives or the client gives up first.
Origins and Host headers both default closed
The HTTP mode table is the security model, and it is short. `ALLOWED_ORIGINS` is a comma-separated CORS list that defaults to empty, which the table describes as no cross-origin browser requests, and it can be set to an explicit allowlist such as `https://app.example.com` or to `*`.
`ALLOWED_HOSTS` is the less familiar of the two. It lists additional `Host` header values to accept, defaults to loopback hosts on the port only, and the table adds the instruction that matters in practice: add the public hostname when binding to `0.0.0.0`. So exposing the server means two edits, the bind address and the host list, and doing only the first produces a server that answers on the network but rejects requests carrying a real hostname.
That is why the two UNSAFE scripts set the bind address and the origin wildcard together. They do not set `ALLOWED_HOSTS`, which means even that path wants one more variable before it serves a named host.
Version 1.3.0 exists on npm and nowhere else
The package is published as `@perplexity-ai/mcp-server` at version 1.3.0, with an MCP name of `ai.perplexity/mcp-server`, and the repository has no GitHub releases at all. There is no tag to compare the two against, so npm is the only place the version exists.
That matters when something breaks. The usual advice of pinning to a tag has no equivalent here, and the last commit is dated 2026-09-25 while the published version is whatever was pushed to the registry before that. The publish config sets the package to public access, and the exports map exposes the package root and `./package.json` and nothing else, so a consumer importing a deep path into `dist/` would be going outside what the manifest promises.
The tools the server exposes are two at the point where the documentation stops being readable. `perplexity_search` goes to the Search API and returns ranked results with metadata, taking a recency filter, a domain filter and a `search_type` of `fast` for lower latency and cost. `perplexity_ask` is conversational, backed by the Agent API `fast` preset.
Editorial conclusion
This is the server to reach for if you want Perplexity's search and Agent API inside an MCP client, and the remote endpoint at api.perplexity.ai/mcp removes the installation question entirely. For a local install, read the env table before the Docker quickstart, because the two disagree: the run command publishes port 8080 while the container binds 127.0.0.1 by default, and the host allowlist needs your public hostname once you bind 0.0.0.0. Three things to check in order. Whether you need HTTP mode at all, since the default entry point is stdio and needs no ports or allowlists. Whether the project's own label for the exposed configuration, UNSAFE in both the npm script name and the documentation, matches your network. And where the version lives, since 1.3.0 exists on npm with no GitHub release to match it. The last commit is dated 2026-09-25.
Frequently asked questions
How do I run the Perplexity MCP server locally?
Add it through your client with npx. For Claude Code or Codex the command is claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server. Manual setup uses the same mcpServers wrapper with the command npx, the args -y @perplexity-ai/mcp-server, and the key in an env block, in the config file your client reads.
What is the difference between the remote and local Perplexity MCP servers?
The remote one is hosted by Perplexity at https://api.perplexity.ai/mcp over Streamable HTTP, with the API key passed in an Authorization Bearer header, and needs nothing installed. The local one runs on your machine through npx and is configured with environment variables such as PERPLEXITY_API_KEY, PERPLEXITY_TIMEOUT_MS, PERPLEXITY_BASE_URL and PERPLEXITY_LOG_LEVEL.
Does the Perplexity MCP server Docker image work with the documented command?
The image entry point is node dist/http.js and the environment table says BIND_ADDRESS defaults to 127.0.0.1, so docker run -p 8080:8080 publishes a port the server is not listening on inside the container. You also need the public hostname added to ALLOWED_HOSTS once you bind to 0.0.0.0. The manifest's start:http:UNSAFE-public script sets the bind address and a wildcard origin for you.
Which tools does the Perplexity MCP server expose?
perplexity_search performs direct web search through the Perplexity Search API, returning ranked results with metadata, and takes a search_recency_filter, a search_domain_filter and a search_type of fast for lower latency and cost. perplexity_ask is conversational with real-time web search, backed by the Agent API fast preset.
How do I use Perplexity MCP behind a corporate proxy?
Set PERPLEXITY_PROXY to the HTTPS proxy address and port, with credentials in URL form such as https://username:password@your-proxy-host:8080. HTTPS_PROXY and HTTP_PROXY are also read, in that order after PERPLEXITY_PROXY, and with none set the server connects directly. URLs must include https://, and the documentation names 8080, 3128 and 80 as the usual ports.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/perplexityai-modelcontextprotocol)Star history chart for your README
[](https://hysenlabs.com/projects/perplexityai-modelcontextprotocol)Was this useful?