ExpressVPN MCP server technical documentation

Before you can connect to the ExpressVPN MCP server:

1. A MCP-compatible AI client. The tool must support HTTP-based MCP servers.
2. An active ExpressVPN or ExpressVPN for Teams subscription.
3. The latest ExpressVPN beta apps for desktop (macOS, Windows, or Linux).
4. Enable MCP in ExpressVPN:
   • Open the ExpressVPN desktop app.
   • Go to Profile, then toggle on “Enable MCP Server”.
   • The local MCP server will start automatically in the background.

Once enabled, connect your AI tool using one of the options below.

Note that the ports shown below are the default port for our MCP server, which may be different on your machine. When enabling the MCP server, it will show you the port being used—ensure you use that port to replace 20090 below.

Claude Code

Run this command in your terminal:

claude mcp add --transport http expressvpn http://127.0.0.1:20090/mcp

Codex

Add the following to your Codex MCP configuration file:

{
  "mcpServers": {
    "expressvpn": {
      "url": "http://127.0.0.1:20090/mcp"
    }
  }
}

Cursor

1. Open Cursor → Settings
2. Go to Tools & MCP
3. Click + Add custom MCP
4. Enter the following configuration and save:

{
  "mcpServers": {
    "expressvpn": {
      "url": "http://127.0.0.1:20090/mcp",
      "headers": {}
    }
  }
}

LM Studio

1. Open LM Studio → right sidebar → Integrations tab
2. Click Install → Edit mcp.json
3. Enter the configuration below and save:

{
  "mcpServers": {
    "expressvpn": {
      "url": "http://127.0.0.1:20090/mcp",
      "headers": {}
    }
  }
}

VS Code

You can manually configure MCP servers by editing the mcp.json file. There are two locations for this file:

• Workspace: create or open .vscode/mcp.json in your project. Include this file in source control to share MCP server configurations with your team.
• User profile: run the MCP: Open User Configuration command to open the mcp.json file in your user profile. Servers configured here are available across all your workspaces. When you use multiple profiles, each profile can have its own MCP server configuration.

You can also run MCP: Add Server in the Command Palette (⇧⌘P) to add a server through a guided flow, choosing either Workspace or Global as the target.

Enter the configuration below:

{
  "servers": {
    "expressvpn": {
      "type": "http",
      "url": "http://127.0.0.1:20090/mcp"
    }
  }
}

Learn what you can do with ExpressVPN MCP tools.

Now that you’ve enabled the ExpressVPN MCP server, your AI assistant can directly read and control your VPN connection through simple prompts.

These tools are designed to work together. Instead of manually opening the ExpressVPN app to check your status, switch regions, or change protocols, you can do it programmatically or through natural language inside your AI coding environment.

VPN Connection

Status

Connection and Network

Location

Settings (Read)

Settings (Write)

Advanced Protection (Read)

Advanced Protection (Write)

Diagnostics

Health Check

The ExpressVPN MCP server makes VPN state and network controls available directly inside the AI tools where you already work. This lets you automate region switching, enforce network policies, troubleshoot connectivity, and build VPN-related workflows inside LLM-based developer clients.

With the MCP, you can:

• Connect or disconnect the VPN programmatically
• Switch to specific countries or cities for testing
• Query real-time connection state and public/VPN IP
• Change VPN protocols for performance validation
• Enable Network Lock (kill switch)
• Configure Split Tunnel rules for specific applications
• Toggle advanced protection features (block ads, trackers, malicious sites)
• Run speed tests and diagnostics
• Build logic that reacts to VPN state changes

These capabilities support workflows like QA testing, CI/CD validation, geo-based testing, privacy enforcement, and automated troubleshooting.

For example, you might:

• Ask your AI client to connect to Germany before running integration tests.
• Automatically switch between US and UK regions to verify geo-restricted content behavior.
• Confirm the VPN is connected before executing network-dependent scripts.
• Run a speed test after changing protocol from OpenVPN to Lightway.
• Enforce Network Lock before running sensitive tasks.
• Temporarily bypass the VPN for a specific app using Split Tunnel.
• Toggle malware site blocking before testing threat detection behavior.

The ExpressVPN MCP server is designed with your privacy and security in mind.

• Local only: The MCP server runs on localhost and is not accessible from other devices or the internet. VPN control signals never leave your machine.
• Opt-in: MCP is disabled by default. You choose to enable it explicitly in Settings.
• No credential exposure: Your ExpressVPN account credentials are never passed through the MCP interface. The server communicates directly with the local ExpressVPN daemon.
• User-confirmed actions: We recommend keeping human confirmation enabled in your AI tool for any connect or disconnect actions. Your agent will ask before making changes.
• Revoke at any time: Toggle MCP off in Settings to immediately stop the local server. Any connected tools will lose access instantly.

ExpressVPN MCP server not reachable

• Make sure “Enable MCP Server” is toggled on in ExpressVPN Profile → Settings.
• If you’ve just enabled it, restart your AI tool. Some MCP clients only discover servers on startup.

To verify the server is running, open a terminal and run:

curl http://127.0.0.1:20090/mcp

If the server is active, you’ll receive a response. If you get a connection refused error, reopen the ExpressVPN app and check the toggle again.

Speed test hangs or takes too long

expressvpn_speedtest can take 30 seconds or more to complete, depending on your network conditions and the number of servers being tested. This is expected behaviour as the tool is running real throughput measurements, not a ping check.

My AI tool isn’t listed in the setup guide

You can manually add the MCP server using this configuration:

{
  "mcpServers": {
    "expressvpn": {
      "url": "http://127.0.0.1:20090/mcp"
    }
  }
}

Once configured, refresh or start the server. You should see a successful connection and the available tools. If the connection fails or you do not see any tools, double-check that the MCP server is enabled in the ExpressVPN desktop app.

Alternatively, check your tool’s documentation for how to add a local MCP server by URL. If your tool doesn’t support MCP yet, consider reaching out to the developers to request MCP support.

My AI tool is using curl instead of MCP tools

If your AI tool, like Claude Code tries to use curl instead of the ExpressVPN MCP tools, or says a tool like expressvpn_speedtest doesn’t exist, the MCP transport may not have loaded correctly.

What a correct setup looks like

After adding the transport and restarting your AI tool:

• Check if your transport is available. For example, from your terminal, run claude mcp list – Claude should show you the MCP is loaded, like expressvpn: http://localhost:20090/mcp (HTTP) – ✓ Connected
• Run expressvpn_ping. You should get pong back successfully.
• Ask your AI tool to show you all ExpressVPN MCP tools. You should see a full list of tools like expressvpn_connect and expressvpn_set_protocol.

If you don’t see them, the transport likely wasn’t registered correctly.

Fix

If the AI still defaults to curl or does not recognize ExpressVPN MCP tools:

• Restart your AI client
• Re-run the MCP add command
• Confirm you’re using the correct port shown in your ExpressVPN app
• Run expressvpn_ping again, then ask your AI to list available ExpressVPN MCP tools
• Additionally, Claude and many AI tools suggest you work in per project directories. Ensure you’re working in a new directory for your project and add the transport to the current projects settings again.

Connection refused on 127.0.0.1:20090

The local MCP server only runs while the ExpressVPN desktop app is open and MCP is enabled. Check:

• The ExpressVPN desktop app is running
• Profile → Settings → Enable MCP Server is toggled on
• No firewall or security tool is blocking connections on port 20090

How to unblock port 20090 (Firewall guide)

The ExpressVPN MCP server communicates locally with your AI developer tools using port 20090 at the localhost address 127.0.0.1.

Because some operating systems and security programs block local port connections by default, your AI client might return a “connection refused” error. If the MCP server is enabled but your tool can’t connect, you will need to whitelist the port in your system’s firewall.

Windows Defender Firewall

Windows Defender often blocks new local port connections on strict or public network profiles. To manually allow the connection:

1. Click the Start menu and search for Windows Defender Firewall with Advanced Security.
2. Select Inbound Rules on the left panel, then click New Rule on the right panel.
3. Select Port and click Next.
4. Choose TCP, specify 20090 in the “Specific local ports” field, and click Next.
5. Select Allow the connection and apply the rule to your active network profiles.
6. Name the rule (e.g., “ExpressVPN MCP Server”) and click Finish.

macOS privacy settings and firewall

macOS requires explicit permission for terminal applications to communicate over your local network. It may also block the port via the built-in application firewall.

• Fix local network permissions: Go to System Settings > Privacy & Security > Local Network. Find your terminal application (such as Terminal, iTerm2, or Cursor) in the list and ensure the toggle is switched to the ON position.
• Fix the macOS firewall: Go to System Settings > Network > Firewall. Click Options and ensure that ExpressVPN is set to Allow incoming connections.

Linux UFW and iptables setups

If you’re running a strict firewall configuration on Linux, you must allow local loopback traffic on port 20090.

• For UFW (Uncomplicated Firewall): Open your terminal and run the following command to allow localhost traffic on the specific port:

sudo ufw allow from 127.0.0.1 to 127.0.0.1 port 20090 proto tcp

• For iptables: Open your terminal and append the following rule to your input chain:

sudo iptables -A INPUT -p tcp -s 127.0.0.1 -d 127.0.0.1 --dport 20090 -j ACCEPT

Third-party antivirus software

If you use third-party antivirus or endpoint protection software, it may feature a “Web Shield” or “Local Network Monitor” that intercepts localhost traffic. If you still can’t connect after configuring your OS firewall, check your antivirus settings and add an exclusion for 127.0.0.1:20090.