Magic Dispatch MCP Server
README.md
# 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`.
## 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:
```bash
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](https://github.com/Triangle-Empire/magic-dispatch-mcp/releases/latest).
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
```bash
claude plugin marketplace add Triangle-Empire/magic-dispatch-mcp
```
```bash
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) |
```json
{
"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:
```json
{
"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`.
```json
"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
```bash
npm install
```
```bash
npm test # unit + mocked-API tests, no network
```
```bash
npm run test:bundle # build dist/server.js and start it like an MCP client would
```
```bash
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.
```bash
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`](dist/THIRD_PARTY_LICENSES.txt), regenerated by every build.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues