Fulfill 3PL MCP Server

MCP server for searching and managing 3PL (third-party logistics) providers.

Installation

For Users (via npm)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "fulfill-3pl": {
      "command": "npx",
      "args": [
        "-y",
        "fulfill-mcp-server-3pl@latest"
      ],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-key",
        "SLACK_BOT_TOKEN": "optional-slack-token",
        "SLACK_CHANNEL_ID": "optional-channel-id"
      }
    }
  }
}

Then restart Claude Desktop.

For Development

# Clone and install
git clone https://github.com/your-org/fulfill-3pl-mcp.git
cd fulfill-3pl-mcp
npm install

# Configure
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
npm test

Cursor (stdio)

• Name: fulfill-3pl-mcp
• Command: node
• Args: dist/mcp-stdio.js
• Env: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY

Tools

Core (single entrypoint)

• ask(query) → Natural language router that dispatches to:
  • search for discovery (e.g., "3PLs in California with cold storage")
  • recommend for brand matchmaking (e.g., "We are a DTC beauty brand with 5k orders/month")
  • compare for side-by-side analysis (e.g., "Compare ShipBob vs Deliverr")
  • profile for a single provider overview (e.g., "Tell me about Red Stag")

Current Data Mappings

• Names for specialties from public.specialties
• Names for technology partners from public.partners
• Contacts from public.team_members (via three_pl_team_member_works_at)
• Customers from public.customers (via three_pl_providers)
• Locations parsed from warehouse_locations and locations_for_map (text JSON)
• External IDs in metadata.sources: webflow_record_id, salesforce_account_id

Deployment Options

Docker (Production - WebSocket)

docker compose up -d
# Access at ws://localhost:3001

Local Development (stdio)

npm run dev  # Development with hot reload
npm start    # Production (uses transport from .env)

Recent Updates

v1.2.0 - Attribution System Overhaul (2025-01-19)

• ✅ Multi-Source Attribution - Extensible system for PostHog, GA4, Salesforce, and more
• ✅ Partner Referral Tracking - 899 referrals identified with 39 3PL partners auto-matched
• ✅ Unified Attribution View - Combined view with referral → paid → organic → direct hierarchy
• ✅ Attribution Metrics Enhanced - Now includes partner referrals as primary attribution source
• ✅ GA4 Integration Ready - Full documentation for adding Google Analytics data

v1.1.0 - Brand Opportunities

• ✅ Brand Pipeline Tool - Track 4,291 opportunities by stage with conversion metrics
• ✅ Placement Analytics - Analyze 25,498 placements with accept/decline rates
• ✅ Attribution Metrics - Marketing ROI tracking with multi-source support
• ✅ Opportunity Details - Full brand requirements with placement history

Transport Options

• Stdio (default): Standard input/output for local MCP clients
• WebSocket: Remote access on port 3000 (configurable via MCP_WEBSOCKET_PORT)

  MCP_TRANSPORT=websocket npm start

  • Optional auth (recommended for any shared/internal deployment): set MCP_WEBSOCKET_API_KEY and connect with header x-api-key: <key> or authorization: Bearer <key>

Roadmap / Next Tasks

• Salesforce data enrichment (fields already in Supabase)
• Brand proximity matching for matchmaking
• Multi-criteria scoring with confidence levels
• Performance: indexes and Redis caching for high-volume queries
• Relevance scoring improvements

Docker

• docker compose up --build

CI

• GitHub Actions runs typecheck/lint/build/tests on push/PR.