Docker Deployment

This page covers building and running the Perplexity MCP Server as a Docker container. The Docker image is optimized for HTTP mode only — the container entry point is src/http.ts, not the stdio entry point. For stdio-based local deployment, see Local STDIO Deployment (7.1). For HTTP server configuration options such as PORT, BIND_ADDRESS, and ALLOWED_ORIGINS, see HTTP Server Deployment (7.2). For environment variable reference, see Environment Variables Reference (5.1).

---

Dockerfile Structure

The image uses a two-stage build to keep the final image small and free of build-time artifacts.

Diagram: Multi-Stage Docker Build

Sources: Dockerfile1-28

Stage Details

Stage	Base Image	Purpose
builder	node:22.12-alpine	Install all deps, compile TypeScript via tsc
release	node:22-alpine	Copy compiled dist/, install prod deps only, run server

Key build choices:

• --mount=type=cache,target=/root/.npm on the npm install step (Dockerfile8) caches the npm package cache across rebuilds, speeding up subsequent builds.
• --ignore-scripts is passed to both npm install and npm ci to prevent execution of lifecycle scripts in dependencies.
• --omit-dev in the release stage ensures devDependencies (TypeScript, vitest, etc.) are not included in the final image.
• The entry point is node dist/http.js (Dockerfile28), meaning the container always starts in HTTP mode.

Sources: Dockerfile1-28

---

Build Context: What Gets Excluded

The .dockerignore file controls what is sent to the Docker daemon. This prevents large or sensitive directories from being included in the build context.

Excluded Path	Reason
node_modules/	Installed fresh inside the container
dist/	Compiled inside the builder stage
coverage/	Test artifact
.git/	VCS metadata not needed
*.md (except README.md)	Documentation
.env, .env.local	Secrets should not bake into image
*.test.ts, *.test.js	Test files
vitest.config.*	Test tooling config
Dockerfile, .dockerignore	Build tooling

Sources: .dockerignore1-19

---

Building the Image

From the project root:

The tag perplexity-mcp-server is used in all run examples below. Any valid Docker tag may be substituted.

Sources: DOCKER.md14-16

---

Running the Container

HTTP Mode (Default)

The server listens on port 8080 inside the container (Dockerfile26). Port 8080 is mapped to the host with -p 8080:8080. The MCP endpoint is then available at http://localhost:8080/mcp and the health check at http://localhost:8080/health.

Sources: DOCKER.md22-28 Dockerfile26-28

With Custom Timeout

The default request timeout is 5 minutes (300,000 ms). For perplexity_research calls, which may exceed 30 seconds of model processing, a higher timeout is recommended:

Sources: DOCKER.md34-39

With CORS Configuration

To restrict which origins can call the /mcp endpoint, pass ALLOWED_ORIGINS:

Multiple origins can be comma-separated. See HTTP Server Deployment (7.2) for details on how ALLOWED_ORIGINS is parsed.

Sources: DOCKER.md1-103

---

Proxy Configuration

If the container runs in an environment that requires an outbound HTTP proxy to reach api.perplexity.ai, set the proxy via environment variables. The server resolves the proxy URL using a priority chain: PERPLEXITY_PROXY > HTTPS_PROXY > HTTP_PROXY. See Proxy Configuration (5.2) for the full resolution logic.

Without authentication

With authentication

Sources: DOCKER.md43-59

---

Using an Environment File

For deployments with multiple variables, an .env file keeps the docker run command clean. Example .env:

PERPLEXITY_API_KEY=your_key_here
PERPLEXITY_TIMEOUT_MS=600000
PERPLEXITY_PROXY=https://your-proxy-host:8080
PORT=8080

Note: The .env file is excluded from the Docker build context via .dockerignore (.dockerignore11). It is only used at container runtime with --env-file.

Run with:

Sources: DOCKER.md63-76

---

Environment Variables Summary

The following variables are recognized by the container at runtime. All are injected via -e KEY=VALUE or --env-file.

Variable	Required	Default	Notes
PERPLEXITY_API_KEY	Yes	—	Bearer token for Perplexity API
PERPLEXITY_BASE_URL	No	https://api.perplexity.ai	Override API endpoint
PERPLEXITY_TIMEOUT_MS	No	300000	Request timeout in ms
PERPLEXITY_LOG_LEVEL	No	ERROR	DEBUG, INFO, WARN, or ERROR
PORT	No	8080	Port the HTTP server binds to
BIND_ADDRESS	No	0.0.0.0	Interface address
ALLOWED_ORIGINS	No	(all)	Comma-separated CORS origin allowlist
PERPLEXITY_PROXY	No	—	Highest-priority proxy URL
HTTPS_PROXY	No	—	Fallback proxy URL
HTTP_PROXY	No	—	Lowest-priority proxy URL

Sources: DOCKER.md1-103 Dockerfile22

---

MCP Client Integration

Once the container is running, configure any MCP-compatible client to connect to the HTTP endpoint. Example JSON configuration block:

Diagram: Docker Container in the Deployment Topology

Sources: Dockerfile26-28 DOCKER.md79-90

---

STDIO Mode and Docker

The Docker image does not support stdio mode. The ENTRYPOINT is hardcoded to node dist/http.js (Dockerfile28), which starts src/http.ts. If stdio transport is required (e.g., for Cursor or Claude Desktop using process-based MCP), use the npx invocation documented in Local STDIO Deployment (7.1) instead of Docker.

Sources: DOCKER.md92-102 Dockerfile28