Docker Deployment

Deploy Perplexity MCP Server using Docker containers

This guide explains how to build and run the Perplexity MCP Server using Docker for containerized deployments.

Prerequisites

• Docker installed on your system
• A Perplexity API key from the API Portal

Building the Docker Image

1. Build the image

   From the project root directory, build the Docker image:

   docker build -t perplexity-mcp-server .
   

   The Dockerfile uses a multi-stage build process:

   • Builder stage: Installs dependencies and compiles TypeScript
   • Release stage: Creates a minimal production image with only runtime dependencies

Running the Container

HTTP Mode (Default)

The Docker container runs in HTTP mode by default, making it accessible via HTTP requests:

Basic Usage

docker run --rm -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

The server will be accessible at http://localhost:8080/mcp

Using Environment File

1. Create environment file

   Create a .env file with your configuration:

   .env

   PERPLEXITY_API_KEY=your_key_here
   PERPLEXITY_TIMEOUT_MS=600000
   PERPLEXITY_PROXY=https://your-proxy-host:8080
   PORT=8080
   
2. Run with environment file

   Start the container using the environment file:

   docker run --rm -p 8080:8080 --env-file .env perplexity-mcp-server
   

Integration with MCP Clients

When using the HTTP Docker server, configure your MCP client to connect to the HTTP endpoint:

MCP Client Configuration

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

The Docker image is optimized for HTTP mode deployment. For local STDIO usage, the npx method is recommended instead of Docker.

STDIO Mode (Local Development)

For local development with STDIO transport, you can run the server locally without Docker:

npm install
npm run build
PERPLEXITY_API_KEY=your_key_here npm start

STDIO vs HTTP Mode: The Docker container uses HTTP mode, which is ideal for production deployments, cloud platforms, and shared environments. STDIO mode is better suited for local development and direct integration with desktop MCP clients.

Container Configuration

The Docker image exposes port 8080 by default and uses Node.js 22 Alpine for a minimal footprint. The entrypoint runs node dist/http.js to start the HTTP server.

Environment Variables

Variable	Description	Default
PERPLEXITY_API_KEY	Your Perplexity API key (required)	-
PERPLEXITY_TIMEOUT_MS	Request timeout in milliseconds	300000 (5 min)
PERPLEXITY_PROXY	Proxy URL for corporate networks	-
PORT	HTTP server port	8080
BIND_ADDRESS	Network interface to bind to	0.0.0.0
ALLOWED_ORIGINS	CORS origins (comma-separated)	*

For production deployments, consider setting specific ALLOWED_ORIGINS instead of using * to restrict CORS access to trusted domains.