Skip to main content
Glama
Magic Dispatch MCP Server

Magic Dispatch MCP Server

Magic Dispatch MCP server

Read-only access to your Magic Dispatch account from AI tools that run local MCP servers: Claude Desktop, Claude Code, Cursor, VS Code (Copilot), Windsurf, Gemini CLI and others. Ask things like "which routes did Sam finish this week?", "where is order 4812?" or "compare deliveries by driver for the last two weeks".

Tools

All tools only read data (GET requests). Nothing is created, changed or deleted.

Tool

What it returns

list_companies

Companies your email belongs to and which one is selected (works without signing in)

whoami

Signed-in user, role, company and its time zone

list_users

Staff and drivers, filtered by role or search

list_teams

Teams (vehicles) with travel method and drivers

get_routes

Routes in a date range, filtered by status, driver or team (by name)

get_route

One route with its stops in order

get_orders

Orders list, newest first, like the dashboard Orders page; filter by status, search, dates or priority

list_customers

Customers or vendors with contact details, filter by status or search

list_products

Products and services with price, filter by type or search

track

Delivery status for a tracking number

delivery_report

Delivery counts per driver or team, daily/weekly/monthly

get_transactions

Payment transactions in a date range, with total

monthly_billing_summary

Magic Dispatch service invoices per month

How the tools behave:

  • Names, not just ids. Pass "Sam" or "North team". If several match, the tool lists them and asks which one.

  • Compact pages. 25 rows by default, with next_cursor for more.

  • Company time zone. "Today" is today in your company's time zone, not UTC.

  • Role-aware. Driver and customer logins are refused, as in the dashboard. Customer service logins don't get get_transactions, monthly_billing_summary or list_users.

  • Audit. Every API call carries X-Client-Source: mcp.

Related MCP server: Company Data MCP Server

Install

You need Node.js 20 or newer (node --version). Nothing else: the server is a single bundled file with no dependencies to install.

Every install asks for the same three settings. The server connects to the Magic Dispatch staging API (https://api-staging.magicdispatch.com/api/v2); there is no URL to enter. Production isn't used yet, so use your staging login.

Setting

Env variable

Example

Email

MAGIC_EMAIL

Your Magic Dispatch login email

Password

MAGIC_PASSWORD

Your Magic Dispatch password

Company

MAGIC_COMPANY_ID

The company you sign in to, by name (Acme Delivery) or ID (139)

Use a dispatcher, management or customer service login. Driver and customer logins are refused.

Find your company

Like the dashboard login, one email can belong to several companies, and you pick one. To see yours before installing:

npx -y @magicdispatch/mcp companies you@example.com
Companies for you@example.com:

  139      Acme Delivery
  212      Beta Foods  (driver login, can't be used)

Set "Company" to one of these names or IDs.

Already installed with the wrong company? Ask your AI tool "list my Magic Dispatch companies". The list_companies tool works without signing in and shows which one is selected. Sign-in errors also list your companies.

Claude Desktop (one click)

  1. Download magic-dispatch-<version>.mcpb from the latest release.

  2. Double-click it (or drag it onto Claude Desktop, or Settings → Extensions → Install Extension).

  3. Fill in email, password and company, then enable it.

Claude Desktop stores the password in your system keychain.

Claude Code

claude plugin marketplace add Triangle-Empire/magic-dispatch-mcp
claude plugin install magic-dispatch@magic-dispatch-tools

Then, in a Claude Code session:

/plugin configure magic-dispatch@magic-dispatch-tools

The password is stored in your system keychain.

Cursor, Windsurf, Gemini CLI, Claude Desktop (manual) and other MCP clients

These clients start the server with npx, which downloads it from npm on first run. Add this block to the client's config file:

Client

Config file

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)

Windsurf

~/.codeium/windsurf/mcp_config.json

Gemini CLI

~/.gemini/settings.json

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "magic-dispatch": {
      "command": "npx",
      "args": ["-y", "@magicdispatch/mcp"],
      "env": {
        "MAGIC_EMAIL": "you@example.com",
        "MAGIC_PASSWORD": "your-password",
        "MAGIC_COMPANY_ID": "Acme Delivery"
      }
    }
  }
}

Restart the client after saving. These files keep the password in plain text, so don't commit or share them.

VS Code (GitHub Copilot agent mode)

Add .vscode/mcp.json to your project. VS Code asks for the password once and stores it securely, so it never sits in the file:

{
  "inputs": [
    {"type": "promptString", "id": "magic-password", "description": "Magic Dispatch password", "password": true}
  ],
  "servers": {
    "magic-dispatch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@magicdispatch/mcp"],
      "env": {
        "MAGIC_EMAIL": "you@example.com",
        "MAGIC_PASSWORD": "${input:magic-password}",
        "MAGIC_COMPANY_ID": "Acme Delivery"
      }
    }
  }
}

Without npm (from a clone)

Clone the repo and point the client at the bundled file instead of npx. No npm install needed. The company lookup works the same way: node dist/server.js companies you@example.com.

"command": "node",
"args": ["/path/to/magic-dispatch-mcp/dist/server.js"]

Not supported yet

  • ChatGPT, claude.ai (web and mobile) and other cloud-hosted assistants. They only connect to remote MCP servers over HTTPS with OAuth. That needs the hosted connector, which depends on backend OAuth work.

Check it works

Ask your AI tool "Who am I in Magic Dispatch?". It should call whoami and answer with your name, role and company. If it reports a setup error, the message says which setting to fix and, for a company problem, lists your companies.

What it sends, and where

  • The server logs in to the Magic Dispatch API only (https://api-staging.magicdispatch.com/api/v2, POST /users/auth/), keeps the session cookie in memory, and logs in again once if the session expires.

  • It logs tool name, duration and success to stderr: never arguments, results or credentials.

  • No data is sent anywhere else.

Development

npm install
npm test             # unit + mocked-API tests, no network
npm run test:bundle  # build dist/server.js and start it like an MCP client would
npm run inspect      # MCP Inspector against the real API (set the MAGIC_* variables)

To use a local backend, or production once it's enabled, set MAGIC_API_URL (for example https://api.magicdispatch.com/api/v2). Install forms don't ask for it; it's for development only.

npm run validate     # validate the Claude Code plugin

Code lives in server.js and lib/. Clients run the bundle dist/server.js, which is committed: run npm run build and commit dist/ (including THIRD_PARTY_LICENSES.txt) with every code change.

Releasing

  1. Set the same version in package.json, manifest.json, .claude-plugin/plugin.json and server.js.

  2. npm run build, then commit (including dist/server.js) and push.

  3. npm run mcpb builds magic-dispatch.mcpb. Attach it to a GitHub release named v<version>, renamed to magic-dispatch-<version>.mcpb.

  4. npm publish --access public publishes @magicdispatch/mcp (runs build and all tests first). Needs the magicdispatch npm organization.

License

MIT. dist/server.js bundles third-party packages under MIT, ISC and BSD-3-Clause licenses; their notices are in dist/THIRD_PARTY_LICENSES.txt, regenerated by every build.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to databases for MCP-compatible AI tools, allowing schema exploration and SELECT queries without exposing credentials or risking data changes.
      3
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only access to company data across PostgreSQL, MongoDB Atlas, and flat files through MCP tools, allowing AI assistants to query and retrieve information via natural language.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A read-only MCP gateway that enables AI agents to retrieve business data (sales, appointments, clients, inventory, etc.) from the AURON Suite backend with role-based access control, audit logging, and rate limiting.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants and LLM agents to query operational databases through a read-only MCP gateway with table whitelisting, automatic row limits, sensitive-data masking, and audit logging.
      1
      MIT