@fleetx_io/fleetx-mcp-server

An MCP (Model Context Protocol) server that gives AI agents access to the FleetX REST API. Use the hosted server at https://mcp.fleetx.io/mcp (no install) or install locally as an npm package — connect to any MCP-compatible client with no code required.

View on npm

How it Works

1. Hosted: Your AI agent connects to https://mcp.fleetx.io/mcp via URL. Local: Your agent launches this server as a subprocess (npx or global install).
2. The server authenticates — either automatically via credentials (Basic Auth for hosted, env vars for local), or when the agent calls the login tool.
3. After authentication, all available API definitions are fetched and registered as MCP tools with validated inputs.
4. The agent can now call any FleetX API — the server handles auth, validation, and proxying automatically.

Authentication

There are two ways to authenticate:

Option 1: Auto-login (recommended)

• Hosted server: Pass credentials via the Authorization: Basic <base64> header in your MCP config.
• Local server: Pass USERNAME and PASSWORD in the env section of your MCP config.

The server logs in at startup and all tools are available immediately — no manual login step needed.

Option 2: Login via chat

If no credentials are provided, only the login tool is exposed initially. Ask your AI agent to call it with your FleetX credentials, and the remaining tools will be registered dynamically.

The login tool is always available regardless of which option you use, so you can re-authenticate or switch accounts at any time.

Quick Start

Option A: Use directly with npx (no install)

npx -y @fleetx_io/fleetx-mcp-server

Option B: Install globally

npm install -g @fleetx_io/fleetx-mcp-server
fleetx-mcp-server

Hosted MCP Server

Use the hosted FleetX MCP server — no local install required. Connect directly from your AI agent.

URL: https://mcp.fleetx.io/mcp

Configuration & Login

You can authenticate in two ways:

Option 1: Auto-login via Basic Auth header (recommended)

Pass your FleetX credentials in the Authorization header. The server logs in at startup and all tools are available immediately.

To create the Basic Auth value, encode your credentials as username:password in base64:

echo -n "your_fleetx_username:your_fleetx_password" | base64

Use the output in the Authorization header as Basic <base64_string>.

Option 2: Login via chat

Connect without credentials. Only the login tool is available initially. Ask your AI agent to call it with your FleetX username and password, and the remaining tools will be registered after successful login.

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

With auto-login (Basic Auth):

{
  "mcpServers": {
    "fleetx": {
      "url": "https://mcp.fleetx.io/mcp",
      "headers": {
        "Authorization": "Basic <your_base64_encoded_credentials>"
      }
    }
  }
}

Replace <your_base64_encoded_credentials> with the output of: echo -n "username:password" | base64

Without auto-login (login via chat):

{
  "mcpServers": {
    "fleetx": {
      "url": "https://mcp.fleetx.io/mcp"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

With auto-login (Basic Auth):

{
  "mcpServers": {
    "fleetx": {
      "url": "https://mcp.fleetx.io/mcp",
      "headers": {
        "Authorization": "Basic <your_base64_encoded_credentials>"
      }
    }
  }
}

Without auto-login (login via chat):

{
  "mcpServers": {
    "fleetx": {
      "url": "https://mcp.fleetx.io/mcp"
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

With auto-login (Basic Auth):

{
  "mcpServers": {
    "fleetx": {
      "url": "https://mcp.fleetx.io/mcp",
      "headers": {
        "Authorization": "Basic <your_base64_encoded_credentials>"
      }
    }
  }
}

Without auto-login (login via chat):

{
  "mcpServers": {
    "fleetx": {
      "url": "https://mcp.fleetx.io/mcp"
    }
  }
}

After saving, restart your AI agent. The FleetX server will appear in Settings > MCP (or equivalent).

Connect to Your AI Agent (Local Install)

Cursor

Add to .cursor/mcp.json in your project root:

With auto-login (recommended):

{
  "mcpServers": {
    "fleetx": {
      "command": "npx",
      "args": ["-y", "@fleetx_io/fleetx-mcp-server"],
      "env": {
        "USERNAME": "your_fleetx_username",
        "PASSWORD": "your_fleetx_password"
      }
    }
  }
}

With global install + auto-login:

{
  "mcpServers": {
    "fleetx": {
      "command": "fleetx-mcp-server",
      "env": {
        "USERNAME": "your_fleetx_username",
        "PASSWORD": "your_fleetx_password"
      }
    }
  }
}

Without auto-login (login via chat):

{
  "mcpServers": {
    "fleetx": {
      "command": "npx",
      "args": ["-y", "@fleetx_io/fleetx-mcp-server"]
    }
  }
}

With global install, without auto-login:

{
  "mcpServers": {
    "fleetx": {
      "command": "fleetx-mcp-server"
    }
  }
}

Then restart Cursor. The server will appear in Settings > MCP.

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

With auto-login (recommended):

{
  "mcpServers": {
    "fleetx": {
      "command": "npx",
      "args": ["-y", "@fleetx_io/fleetx-mcp-server"],
      "env": {
        "USERNAME": "your_fleetx_username",
        "PASSWORD": "your_fleetx_password"
      }
    }
  }
}

With global install + auto-login:

{
  "mcpServers": {
    "fleetx": {
      "command": "fleetx-mcp-server",
      "env": {
        "USERNAME": "your_fleetx_username",
        "PASSWORD": "your_fleetx_password"
      }
    }
  }
}

Without auto-login (login via chat):

{
  "mcpServers": {
    "fleetx": {
      "command": "npx",
      "args": ["-y", "@fleetx_io/fleetx-mcp-server"]
    }
  }
}

With global install, without auto-login:

{
  "mcpServers": {
    "fleetx": {
      "command": "fleetx-mcp-server"
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

With auto-login (recommended):

{
  "mcpServers": {
    "fleetx": {
      "command": "npx",
      "args": ["-y", "@fleetx_io/fleetx-mcp-server"],
      "env": {
        "USERNAME": "your_fleetx_username",
        "PASSWORD": "your_fleetx_password"
      }
    }
  }
}

With global install + auto-login:

{
  "mcpServers": {
    "fleetx": {
      "command": "fleetx-mcp-server",
      "env": {
        "USERNAME": "your_fleetx_username",
        "PASSWORD": "your_fleetx_password"
      }
    }
  }
}

Without auto-login (login via chat):

{
  "mcpServers": {
    "fleetx": {
      "command": "npx",
      "args": ["-y", "@fleetx_io/fleetx-mcp-server"]
    }
  }
}

With global install, without auto-login:

{
  "mcpServers": {
    "fleetx": {
      "command": "fleetx-mcp-server"
    }
  }
}

Usage

Once connected:

• If you used auto-login: All FleetX tools are ready immediately. Just ask "Show me all vehicles" or "Get trip history for vehicle KA01AB1234".
• If you didn't pass credentials: Ask the agent to "Log in to FleetX with username X and password Y" first. After login, all tools become available.

Available Tools (after login)

Tools are generated dynamically from your FleetX account's API definitions. Common examples:

| Tool | Description | |------|-------------| | login | Authenticate with FleetX (required first) | | vehicle_listing | List all vehicles | | vehicle_realtime_api | Get real-time vehicle data | | create_job | Create a new job | | job_status_api | Check job status | | get_trip_history_by_vehicle_within_a_given_time_range | Trip history for a vehicle | | fetch_tagsfor_a_given_account | Get all tags | | real_time_analytics_api_by_vehicle_number | Analytics by vehicle |

The full list depends on your account's enabled APIs.

Security

• Credentials passed via env are held only as process environment variables — never logged or stored on disk.
• Credentials are sent only to the FleetX login endpoint.
• The access token is held in memory for the session duration and never exposed in tool responses.
• Token is automatically cleared on 401/403 errors, requiring re-login.

Testing with MCP Inspector

With npx (no install):

npx -y @modelcontextprotocol/inspector npx -y @fleetx_io/fleetx-mcp-server

After installing the package globally:

npx -y @modelcontextprotocol/inspector fleetx-mcp-server

This opens a web UI where you can connect, call login, browse all discovered tools, and test them interactively.

Requirements

• Node.js >= 20

License

ISC