Machship MCP Server

A Model Context Protocol server that integrates AI assistants with the Machship freight management platform. Built on a production-ready TypeScript foundation, it provides comprehensive access to Machship for consignment management, quoting, labelling, manifesting, and more — through any MCP-compatible AI client.

Built by Devkind — cutting-edge software development serving businesses globally.

Features

• Full Machship API Coverage: 125 tools across 21 modules — consignments, quotes, labels, manifests, carriers, locations, and more
• Dual Transport Support: STDIO and HTTP transports for AI assistant and web integration
• Type Safety: Full TypeScript implementation with Zod schema validation
• npx Ready: Zero-install usage via npx @devkind/machship-mcp
• Docker Support: Production Docker image on Docker Hub
• Any MCP Client: Works with Claude Desktop, Cursor, VS Code, Windsurf, and more

Available Tools

| Module | Tools | |---|---| | Authenticate | ping | | Attachments | get, POD report, batch download, upload | | CarrierInvoices | list, entries, reprice, auto-reconcile | | CommercialInvoices | upload | | Companies | list, carriers/accounts/services | | CompanyItems | get, list, by-sku, complex variants, create, delete | | CompanyLocations | get, list, create, edit, permanent pickups | | Consignments | get, batch, by-reference, create, edit, delete, search, statuses | | Consolidation | group, perform, group+perform | | CustomSchemas | get all, get by id, create, update, delete | | FinancialInvoice | list posted, get by document number | | Identities | create, get, list, update, delete, enable/disable, link to companies, public keys | | IdentityProviders | get by id, list by company/user/organisation | | Labels | consignment PDF, item PDF, manifest PDF, batch zip, print, dangerous goods | | Locations | search, exact match, with options | | Manifests | list, group, manifest/book, rebook pickup | | Notes | get consignment notes | | OrganisationLinks | get links, add, remove, public key management | | PendingConsignments | create, get, batch, by-reference, recent, delete | | Quotes | create, create with complex items, list, get | | Routes | get routes, batch routes, complex items routes |

Total: 125 tools

Quick Start (No Install Required)

No cloning, no global installs — just Node.js 18+ and a Machship API token.

Step 1 — Get your Machship API token

1. Log into your Machship account
2. Go to Settings → API
3. Generate an API token — this is your MACHSHIP_API_TOKEN

Step 2 — Add to your MCP client (pick one below)

Step 3 — Restart your client and start chatting

To verify it works, ask: "Ping the Machship API" — you should get a successful response.

Client Setup

Claude Desktop

Open Settings → Developer → Edit Config, or edit the file directly (create it if it doesn't exist):

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

{
  "mcpServers": {
    "machship": {
      "command": "npx",
      "args": ["-y", "@devkind/machship-mcp"],
      "env": {
        "MACHSHIP_API_TOKEN": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop — the Machship tools will appear automatically.

Claude Code (CLI)

# Prompts for the token without echoing it or saving it to shell history
read -rs MACHSHIP_API_TOKEN
claude mcp add --scope local machship -e MACHSHIP_API_TOKEN="$MACHSHIP_API_TOKEN" -- npx -y @devkind/machship-mcp

--scope local stores the token in your user config (~/.claude.json), outside the repository. Never put the token in a project .mcp.json — that file is meant to be committed.

One-click install:

Manual setup:

Go to Cursor Settings → MCP → Add new MCP Server:

• Name: Machship MCP
• Type: command
• Command: npx -y @devkind/machship-mcp
• Environment variable: MACHSHIP_API_TOKEN = your-token-here

Install via the VS Code CLI (one command):

code --add-mcp '{"name":"machship","command":"npx","args":["-y","@devkind/machship-mcp"],"env":{"MACHSHIP_API_TOKEN":"your-token-here"}}'

Or follow the MCP setup guide and use this config:

{
  "mcpServers": {
    "machship": {
      "command": "npx",
      "args": ["-y", "@devkind/machship-mcp"],
      "env": {
        "MACHSHIP_API_TOKEN": "your-token-here"
      }
    }
  }
}

Follow the Windsurf MCP documentation and add to your MCP configuration file:

{
  "mcpServers": {
    "machship": {
      "command": "npx",
      "args": ["-y", "@devkind/machship-mcp"],
      "env": {
        "MACHSHIP_API_TOKEN": "your-token-here"
      }
    }
  }
}

Go to Advanced settings → Extensions → Add custom extension:

• Name: Machship MCP
• Type: STDIO
• Command: npx -y @devkind/machship-mcp
• Environment variable: MACHSHIP_API_TOKEN = your-token-here

Go to Program in the right sidebar → Install → Edit mcp.json and add:

{
  "mcpServers": {
    "machship": {
      "command": "npx",
      "args": ["-y", "@devkind/machship-mcp"],
      "env": {
        "MACHSHIP_API_TOKEN": "your-token-here"
      }
    }
  }
}

Go to Settings → AI → Manage MCP Servers → + Add, or use the slash command /add-mcp in the Warp prompt:

{
  "mcpServers": {
    "machship": {
      "command": "npx",
      "args": ["-y", "@devkind/machship-mcp"],
      "env": {
        "MACHSHIP_API_TOKEN": "your-token-here"
      }
    }
  }
}

Run directly (test / CLI use)

# STDIO mode — pipe JSON-RPC directly
MACHSHIP_API_TOKEN=your-token npx -y @devkind/machship-mcp

# HTTP mode — exposes a local MCP endpoint
MACHSHIP_API_TOKEN=your-token TRANSPORT=http npx -y @devkind/machship-mcp
# MCP endpoint: http://localhost:3000/mcp
# Health check:  http://localhost:3000/health

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | MACHSHIP_API_TOKEN | Yes | — | Machship API token (sent in the token header) | | MACHSHIP_API_URL | No | https://live.machship.com | Override API base URL | | TRANSPORT | No | stdio | stdio or http | | PORT | No | 3000 | HTTP port (when TRANSPORT=http) |

Example Interactions

Once connected, ask your AI assistant:

"Search for freight routes from Melbourne 3000 to Sydney 2000 for a 10kg parcel"
"Create a consignment for company 123 shipping to Brisbane"
"Get all unmanifested consignments for company 456"
"What carriers and services are available for company 789?"
"Get the label PDF for consignment 12345"
"Show me completed consignments from last week"
"Create a quote with complex items for express delivery"

Transport Modes

| Mode | When to use | |------|-------------| | stdio (default) | AI desktop clients (Claude Desktop, Cursor, VS Code, etc.) — JSON-RPC over stdin/stdout | | http | Web integrations, remote servers, or anything that needs an HTTP MCP endpoint |

Set the mode via the TRANSPORT environment variable (see Environment Variables above).

Docker

Pull and run from Docker Hub — no Node.js required:

docker run -e MACHSHIP_API_TOKEN=your-token \
           -e TRANSPORT=http \
           -p 3000:3000 \
           devkind/machship-mcp:latest

For stdio mode in MCP clients:

{
  "mcpServers": {
    "machship": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-e", "MACHSHIP_API_TOKEN=your-token-here",
               "devkind/machship-mcp:latest"]
    }
  }
}

Development

Quick Start

This repository uses Yarn 1 only (yarn.lock). Do not run npm install.

Development needs Node.js 22.14+ or 24.10+ (required by the release tooling). Running the published server needs only Node.js 18+.

# Clone and install
git clone https://github.com/devkindhq/machship-mcp.git
cd machship-mcp
yarn install

# Build
yarn build

# Run in STDIO mode
MACHSHIP_API_TOKEN=your-token yarn start

# Run in HTTP mode
MACHSHIP_API_TOKEN=your-token TRANSPORT=http yarn start

# Development with watch mode
MACHSHIP_API_TOKEN=your-token yarn dev

Scripts

yarn build                  # Compile TypeScript to dist/
yarn dev                    # Watch mode with tsx
yarn start                  # Run compiled server
yarn clean                  # Remove dist/
yarn lint                   # ESLint + Prettier check on src/
yarn format                 # Format src/ with Prettier
yarn bundle                 # Build machship-mcp.mcpb (MCPB bundle for Smithery)

# Docker
yarn docker:build           # Build image as devkind/machship-mcp:latest
yarn docker:build:version   # Tag with package version + latest
yarn docker:run             # Run locally in HTTP mode on port 3000
yarn docker:push            # Push latest to Docker Hub
yarn docker:push:version    # Push version tag + latest to Docker Hub
yarn docker:release         # Full pipeline: build + tag + push

License

ISC License

Resources

• MCP Specification
• MCP SDK
• Machship API Documentation
• Devkind — the team behind this server