Exa MCP Server 🔍 (Self-Hosted Fork)

This is a fork of the original exa-labs/exa-mcp-server with added support for self-hosting on VPS with Docker, Nginx, and GitHub Actions auto-deployment.

---

What's Different in This Fork?

This fork extends the original Exa MCP server with VPS self-hosting capabilities using Streamable HTTP transport. Here's what has been added:

New Features & Improvements

Feature	Description
All Tools Enabled by Default	Unlike the original (which only enables 2 tools), this fork enables all 8 tools by default
Streamable HTTP Transport	New src/http-server.ts entry point using Express + @modelcontextprotocol/sdk Streamable HTTP transport for VPS deployment
Docker Support	Production-ready Dockerfile with multi-stage build, non-root user, and health checks
Docker Compose	docker-compose.yml for easy container orchestration with environment variable support
Nginx Configuration	deploy/nginx-mcp.conf with reverse proxy settings, SSE support, and proper timeouts
GitHub Actions CI/CD	.github/workflows/deploy-vps.yml for automatic deployment on push to main
Health Endpoint	/health endpoint for container health checks and monitoring
Analytics Dashboard	Full Chart.js dashboard with persistent storage, 4 interactive charts, and auto-refresh
Persistent Analytics	Analytics data survives container restarts via Docker volume (/app/data/analytics.json)
Session Management	Proper MCP session handling with session ID tracking
Flexible API Key	Support for API key via query parameter, header, or environment variable

New Files Added

├── src/http-server.ts          # HTTP server entry point (Streamable HTTP)
├── docker-compose.yml          # Docker orchestration
├── deploy/
│   └── nginx-mcp.conf          # Nginx reverse proxy configuration
└── .github/
    └── workflows/
        └── deploy-vps.yml      # Auto-deployment workflow

Updated Files

• package.json - Added express, cors, and new scripts (build:tsc, dev:http, start:http)
• Dockerfile - Rewritten for HTTP server deployment with proper security
• tsconfig.json - Output to build/ directory for TypeScript compilation

---

Self-Hosted VPS Deployment 🚀

Architecture

Client (Claude, Cursor, Windsurf, etc.)
    ↓ HTTPS
https://mcp.yourdomain.com/exa/mcp
    ↓
Nginx (SSL termination + reverse proxy)
    ↓ HTTP
Docker Container (port 8087 → 8080)
    ↓
Exa MCP Server (Streamable HTTP Transport)
    ↓
Exa API

Quick Start (VPS)

1. Clone to your VPS:

   mkdir -p /opt/mcp-servers/mcp-exa
   cd /opt/mcp-servers/mcp-exa
   git clone https://github.com/hithereiamaliff/mcp-exa.git .
   

2. Create .env file:

   echo "EXA_API_KEY=your-exa-api-key" > .env
   

3. Start the container:

   docker compose up -d --build
   

4. Add Nginx location block (add to your server config):

   location /exa/ {
       proxy_pass http://127.0.0.1:8087/;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_connect_timeout 60s;
       proxy_send_timeout 60s;
       proxy_read_timeout 300s;
       proxy_buffering off;
       proxy_cache off;
       client_max_body_size 10M;
   }
   

5. Reload Nginx:

   sudo nginx -t && sudo systemctl reload nginx
   

Client Configuration (Self-Hosted)

{
  "mcpServers": {
    "exa": {
      "transport": "streamable-http",
      "url": "https://mcp.yourdomain.com/exa/mcp?apiKey=YOUR_EXA_API_KEY"
    }
  }
}

GitHub Actions Auto-Deployment

Set up these secrets in your GitHub repository:

• VPS_HOST - Your VPS IP address
• VPS_USERNAME - SSH username (e.g., root)
• VPS_SSH_KEY - Private SSH key
• VPS_PORT - SSH port (usually 22)

Pushing to main branch will automatically deploy to your VPS.

Endpoints

Endpoint	Description
/	Server info and available endpoints
/health	Health check (returns server status and uptime)
/mcp	MCP protocol endpoint
/analytics	Full analytics summary (JSON)
/analytics/tools	Tool usage statistics (JSON)
/analytics/dashboard	Visual Chart.js dashboard with 4 interactive charts
/analytics/import	Import backup data (POST, requires ANALYTICS_IMPORT_KEY)

Default Tools (All Enabled)

Unlike the original Exa MCP server which only enables web_search_exa and get_code_context_exa by default, this self-hosted fork enables all 8 tools out of the box:

• web_search_exa - Real-time web search
• get_code_context_exa - Code snippets and documentation search
• deep_search_exa - Advanced web search with query expansion
• crawling_exa - Extract content from specific URLs
• deep_researcher_start - Start comprehensive AI research tasks
• deep_researcher_check - Check research task status and results
• linkedin_search_exa - Search LinkedIn profiles and companies
• company_research_exa - Research companies and organizations

To restrict tools, set the ENABLED_TOOLS environment variable in your .env file:

ENABLED_TOOLS=web_search_exa,get_code_context_exa

Analytics Dashboard

The self-hosted version includes a full-featured analytics dashboard with:

• Persistent Storage - Analytics data saved to /app/data/analytics.json and survives container restarts
• 4 Interactive Charts - Tool usage (doughnut), hourly requests (line), endpoints (bar), clients (horizontal bar)
• Real-time Stats - Total requests, tool calls, unique clients, most used tool
• Recent Activity Feed - Last 20 tool calls with timestamps and client info
• Auto-refresh - Dashboard updates every 30 seconds
• Backup/Restore - Import endpoint for restoring analytics from backups

Dashboard URL: https://mcp.yourdomain.com/exa/analytics/dashboard

Environment Variables:

ANALYTICS_DIR=/app/data                    # Where to store analytics (default: /app/data)
ANALYTICS_IMPORT_KEY=your-secret-key       # Optional key for import endpoint security

---

Original Exa MCP Features

Exa Code: fast, efficient web context for coding agents

Vibe coding should never have a bad vibe. exa-code is a huge step towards coding agents that never hallucinate.

When your coding agent makes a search query, exa-code searches over billions of Github repos, docs pages, Stackoverflow posts, and more, to find the perfect, token-efficient context that the agent needs to code correctly. It's powered by the Exa search engine.

Examples of queries you can make with exa-code:

• use Exa search in python and make sure content is always livecrawled
• use correct syntax for vercel ai sdk to call gpt-5 nano asking it how are you
• how to set up a reproducible Nix Rust development environment

✨ Works with Cursor and Claude Code! Use the HTTP-based configuration format:

{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": {}
    }
  }
}

You can enable specific tool(s) using the tools parameter (if multiple, then with a comma-separated list):

https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa

Or enable all tools:

https://mcp.exa.ai/mcp?tools=web_search_exa,deep_search_exa,get_code_context_exa,crawling_exa,company_research_exa,linkedin_search_exa,deep_researcher_start,deep_researcher_check

You may include your exa api key in the url like this:

https://mcp.exa.ai/mcp?exaApiKey=YOUREXAKEY

Note: By default, only web_search_exa and get_code_context_exa are enabled. Add other tools as needed using the tools parameter.

---

A Model Context Protocol (MCP) server that connects AI assistants like Claude to Exa AI's search capabilities, including web search, research tools, and our new code search feature.

Remote Exa MCP 🌐

Connect directly to Exa's hosted MCP server (instead of running it locally).

Remote Exa MCP URL

https://mcp.exa.ai/mcp

Claude Desktop Configuration for Remote MCP

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.exa.ai/mcp"
      ]
    }
  }
}

Cursor and Claude Code Configuration for Remote MCP

For Cursor and Claude Code, use this HTTP-based configuration format:

{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": {}
    }
  }
}

Codex Configuration for Remote MCP

Open your Codex configuration file:

code ~/.codex/config.toml

Add this configuration:

[mcp_servers.exa]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"]
env = { EXA_API_KEY = "your-api-key-here" }

Replace your-api-key-here with your actual Exa API key from dashboard.exa.ai/api-keys.

Claude Code Plugin

The easiest way to get started with Exa in Claude Code, using plugins:

# Add the Exa marketplace
/plugin marketplace add exa-labs/exa-mcp-server

# Install the plugin
/plugin install exa-mcp-server

Then set your API key:

export EXA_API_KEY="your-api-key-here"

Get your API key from dashboard.exa.ai/api-keys.

NPM Installation

npm install -g exa-mcp-server

Using Claude Code

claude mcp add exa -e EXA_API_KEY=YOUR_API_KEY -- npx -y exa-mcp-server

Using Exa MCP through Smithery

To install the Exa MCP server via Smithery, head over to:

smithery.ai/server/exa

Configuration ⚙️

1. Configure Claude Desktop to recognize the Exa MCP server

You can find claude_desktop_config.json inside the settings of Claude Desktop app:

Open the Claude Desktop app and enable Developer Mode from the top-left menu bar.

Once enabled, open Settings (also from the top-left menu bar) and navigate to the Developer Option, where you'll find the Edit Config button. Clicking it will open the claude_desktop_config.json file, allowing you to make the necessary edits.

OR (if you want to open claude_desktop_config.json from terminal)

For macOS:

1. Open your Claude Desktop configuration:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

1. Open your Claude Desktop configuration:

code %APPDATA%\Claude\claude_desktop_config.json

2. Add the Exa server configuration:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace your-api-key-here with your actual Exa API key from dashboard.exa.ai/api-keys.

3. Available Tools & Tool Selection

The Exa MCP server includes powerful tools for developers and researchers:

🌐 Tools

• get_code_context_exa: Search and get relevant code snippets, examples, and documentation from open source libraries, GitHub repositories, and programming frameworks. Perfect for finding up-to-date code documentation, implementation examples, API usage patterns, and best practices from real codebases.
• web_search_exa: Performs real-time web searches with optimized results and content extraction.
• deep_search_exa: Deep web search with smart query expansion and high-quality summaries for each result.
• company_research: Comprehensive company research tool that crawls company websites to gather detailed information about businesses.
• crawling: Extracts content from specific URLs, useful for reading articles, PDFs, or any web page when you have the exact URL.
• linkedin_search: Search LinkedIn for companies and people using Exa AI. Simply include company names, person names, or specific LinkedIn URLs in your query.
• deep_researcher_start: Start a smart AI researcher for complex questions. The AI will search the web, read many sources, and think deeply about your question to create a detailed research report.
• deep_researcher_check: Check if your research is ready and get the results. Use this after starting a research task to see if it's done and get your comprehensive report.

Note: By default, only web_search_exa and get_code_context_exa are enabled. You can enable additional tools using the tools= parameter (see examples below).

💻 Setup for Code Search Only (Recommended for Developers)

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": [
        "-y",
        "exa-mcp-server",
        "tools=get_code_context_exa"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Enable All Tools:

You can either enable all tools or any specfic tools. Use a comma-separated list to enable the tools you need:

{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": [
        "-y",
        "exa-mcp-server",
        "tools=get_code_context_exa,web_search_exa,deep_search_exa,company_research_exa,crawling_exa,linkedin_search_exa,deep_researcher_start,deep_researcher_check"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using via NPX

If you prefer to run the server directly, you can use npx:

# Run with default tools only (web_search_exa and get_code_context_exa)
npx exa-mcp-server

# Enable specific tools only
npx exa-mcp-server tools=web_search_exa

# All tools
npx exa-mcp-server tools=web_search_exa,deep_search_exa,get_code_context_exa,crawling_exa,company_research_exa,linkedin_search_exa,deep_researcher_start,deep_researcher_check

---

Troubleshooting (Self-Hosted)

502 Bad Gateway

• Container not running: docker compose up -d --build
• Check container logs: docker compose logs -f
• Verify port mapping: docker ps

Container Build Fails

• Check if --ignore-scripts is in Dockerfile for npm ci
• Verify source files are copied before npm run build:tsc
• Check TypeScript compilation errors in logs

Health Check Failing

• Container might still be starting (wait 10-30 seconds)
• Check if health endpoint returns valid JSON: curl http://localhost:8087/health

---

Credits

• Original MCP Server: exa-labs/exa-mcp-server by team Exa
• VPS Deployment Additions: Self-hosting support with Docker, Nginx, and GitHub Actions

Built with ❤️ by team Exa | VPS deployment fork by @hithereiamaliff