Self-Host MCP Server with Node.js: Local and Server Deployment

import { Steps } from ‘@astrojs/starlight/components’;

Self-Host MCP Server with Node.js

Run the Xplorr MCP server directly with Node.js — no Docker required. This is the simplest self-hosting option for development, testing, or environments where Docker isn’t available.

Prerequisites

Node.js 20+ — Check with node --version
npm or yarn — Comes with Node.js
An Xplorr API token — Get one at console.xplorr.io > Settings > API Tokens

Setup

Clone the repository

git clone https://github.com/Xplorrio/xplorr-mcp-server.git
cd xplorr-mcp-server

Install dependencies
Terminal window
```
npm install
```
Configure your API token
Terminal window
```
cp .env.example .env
```
Edit .env:
Terminal window
```
XPLORR_API_TOKEN=xplorr_your_token_here
```

Start the server

npm start

Output:

MCP server running on http://localhost:3005
Mode: single-tenant
Tools: 26

Verify it’s healthy

In another terminal:

curl http://localhost:3005/health

{"status":"ok","service":"xplorr-mcp","tools":26,"mode":"single-tenant"}

Connect Claude Desktop

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "xplorr": {
      "url": "http://localhost:3005/mcp"
    }
  }
}

Restart Claude Desktop. The 26 Xplorr tools appear in Claude’s tool list.

Development Mode

Run with auto-reload for development:

npm run dev

The server restarts automatically when you edit source files. Useful if you’re modifying the MCP server or adding custom tools.

Running as a Background Service

For persistent deployment on a server (without Docker), use a process manager:

Using pm2:

npm install -g pm2
pm2 start npm --name xplorr-mcp -- start
pm2 save
pm2 startup  # auto-start on reboot

Using systemd (Linux):

Create /etc/systemd/system/xplorr-mcp.service:

[Unit]
Description=Xplorr MCP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/xplorr-mcp-server
EnvironmentFile=/opt/xplorr-mcp-server/.env
ExecStart=/usr/bin/node src/index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable xplorr-mcp
sudo systemctl start xplorr-mcp

Pointing at a Self-Hosted Backend

If you run the full Xplorr platform on your own infrastructure, override the API URL:

XPLORR_API_TOKEN=xplorr_your_token_here
XPLORR_API_URL=https://api.your-company.com

The MCP server appends /api/v1/... to this URL for all API calls.

Environment Variables

Variable	Required	Default	Description
`XPLORR_API_TOKEN`	Yes	—	Your `xplorr_` API token
`XPLORR_API_URL`	No	`https://api.xplorr.io`	Override for on-prem backends
`PORT`	No	`3005`	Listen port

See the Configuration reference for details.

Troubleshooting

Error: Cannot find module

Run npm install first. If you pulled recent changes, run it again.

Port 3005 already in use

Either stop whatever is using it (lsof -i :3005) or change the port in .env:

PORT=3006

Update your Claude Desktop config to match.

Token exchange fails / auth errors on tool calls

Verify your token is valid at console.xplorr.io > Settings > API Tokens
Make sure the server can reach https://api.xplorr.io (or your custom XPLORR_API_URL)
Check for network/proxy issues: curl https://api.xplorr.io/api/v1/health

FAQ

What Node.js versions are supported? Node.js 20 and above. The server uses ES modules and modern JavaScript features.

Can I run this alongside the Docker version? Yes, but use different ports. Set PORT=3006 for one of them.

How do I update to the latest version?

cd xplorr-mcp-server
git pull
npm install
npm start

MCP Overview — All 26 tools and architecture
Self-Host with Docker — Container-based alternative
Hosted MCP — Zero-setup alternative
Configuration — Environment variable reference