SearchCarriers Tools

Evidence-driven motor carrier operations for Claude Code and MCP clients.

Search, source, qualify, monitor, and reconcile motor carriers directly from your terminal. Five plugins, fourteen focused skills, and seven composed workflows turn SearchCarriers API evidence into bounded operational decisions.

The tools are open source under Apache-2.0. They are an independent client for the SearchCarriers service; API access and production data use still require an appropriate SearchCarriers account and are subject to its terms.

Built for freight brokers, safety teams, and logistics operations that need sourceable evidence, visible unknowns, and a concrete next action.

Start Here

Open Claude Code in this repo and say:

Walk me through getting started with SearchCarriers

Or paste the repo URL into any LLM and ask it to help you set up.

Related MCP server: MobusMCP

Quick Start

Up and running in under 2 minutes:

git clone https://github.com/jeremylongshore/searchcarriers-tools.git
cd searchcarriers-tools && ./scripts/setup-dev.sh

Set your API key:

export SEARCHCARRIERS_API_KEY="your_id|your_token"

Then try your first lookup in Claude Code:

/sc-lookup JB Hunt

Plugin Catalog

Stackable Pipeline

The three stackable plugins cover retrieval, analysis, and output. The caller chooses when to pass evidence between stages and remains the decision owner.

                        STACKABLE PIPELINE
  ================================================================

  +-----------------------+     +------------------------+     +-------------------------+
  |   CARRIER INTEL       |     |   RISK ENGINE          |     |   OPS REPORTER          |
  |   (INPUT)             |---->|   (ANALYSIS)           |---->|   (OUTPUT)              |
  |                       |     |                        |     |                         |
  |   carrier_lookup      |     |   risk_score           |     |   generate_report       |
  |   carrier_profile     |     |   qualification_reports|     |   generate_fleet        |
  |   entity_map          |     |   vetting_check        |     |   generate_compare      |
  |   fleet_summary       |     |   insurance_check      |     |   export_data           |
  |                       |     |   compliance_audit     |     |                         |
  |                       |     |                        |     |                         |
  |   Min: Free           |     |   Min: Pro             |     |   Min: Pro              |
  +-----------------------+     +------------------------+     +-------------------------+

  Example: "/sc-lookup KLLM" --> carrier data --> risk assessment --> formatted vetting report

Standalone plugins operate independently:

  +------------------------+     +-------------------------+
  |   WATCHDOG             |     |   API BRIDGE            |
  |   (MONITORING)         |     |   (INTEGRATION)         |
  |                        |     |                         |
  |   manage_watchlist     |     |   api_health            |
  |   get_alerts           |     |   bulk_lookup           |
  |   route_alert          |     |   tms_sync              |
  |   monitor_compliance   |     |   webhook_manage        |
  |                        |     |                         |
  |   Min: Pro+            |     |   Min: SMB              |
  +------------------------+     +-------------------------+

Skill Catalog

Fourteen skills are organized by carrier job. Each package includes a focused SKILL.md, a decision playbook, and a behavioral eval-spec.yaml.

Search & Discovery

Safety & Compliance

Vetting & Risk

Operations

Tier Matrix

Features available at each SearchCarriers subscription tier:

Tier gating is enforced at three layers: MCP server startup (API key check), per-tool tier validation (returns upgrade URL if insufficient), and skill prerequisites (documented in each SKILL.md).

API contract

SearchCarriers capabilities currently span three API versions:

• v3 for search, company field selection, equipment, and crashes

• v2 for qualification reports

• v1 for VIN/SCAC lookup, detailed history, export, and watches

The exact routes, advanced search filters, verified parameter names, data-handling boundary, and source links live in API-DISCOVERY.md. In particular, v3 uses docketNumber, perPage, addressState, and addressCity; older names may be silently ignored even when the API returns HTTP 200.

The product research behind each workflow is recorded in docs/PAIN-POINT-RESEARCH.md.

Premium Workflows

Paid add-on workflows that chain multiple plugins together for automated carrier monitoring and reporting.

Pro Tier

Pro+ Tier

SMB / Enterprise Tier

First 10 Minutes

What a new user does after cloning:

Minute 0-1: Clone and setup.

git clone https://github.com/jeremylongshore/searchcarriers-tools.git
cd searchcarriers-tools && ./scripts/setup-dev.sh

The setup script installs dependencies, validates your environment, and confirms everything is wired correctly.

Minute 1-2: Configure your API key.

Get your key from SearchCarriers API settings, then:

export SEARCHCARRIERS_API_KEY="your_id|your_token"

Add it to your .env file for persistence (see .env.example).

Minute 2-4: Run your first carrier lookup.

Open Claude Code and try:

/sc-lookup Werner Enterprises

You should see carrier identity, contact info, fleet size, and operating authority pulled from 4M+ companies.

Minute 4-6: Try a carrier profile.

Get the full picture for a carrier by DOT number:

/sc-profile 69494

This pulls search results, insurance, authority status, and equipment data into a single view.

Minute 6-8: Score a carrier's risk (Pro tier).

/sc-risk 69494

The risk engine interprets raw safety data into a plain-language risk assessment with pass/review/fail recommendation.

Minute 8-10: Generate a vetting report (Pro tier).

/sc-report 69494

Produces a formatted vetting report combining carrier data, risk scores, and compliance status -- ready to share with your ops team.

What's next: Add carriers to your watch list with /sc-watch, set up Slack alerts, or bulk-process a CSV of carriers with /sc-bulk.

Development

Validate

Run the single validation script to check all plugins and skills:

./scripts/validate.sh --verbose

This validates:

• Plugin manifest (plugin.json) required fields

• SKILL.md frontmatter (name format, description length, allowed tools)

• No absolute paths in skills (must use {baseDir}/)

• Bash tool scoping (Bash(python:*) not raw Bash)

• Secret scanning

Test

pytest -v

Tests cover plugin structure validation, skill spec compliance, and MCP server responses.

Project Structure

searchcarriers/
├── plugins/                     # 5 Claude Code plugins
│   ├── searchcarriers-carrier-intel/    # Stackable: INPUT
│   ├── searchcarriers-risk-engine/      # Stackable: ANALYSIS
│   ├── searchcarriers-ops-reporter/     # Stackable: OUTPUT
│   ├── searchcarriers-watchdog/         # Standalone: MONITORING
│   └── searchcarriers-api-bridge/       # Standalone: INTEGRATION
├── skills/                      # 14 standalone skills
│   ├── search-discovery/        # 3 skills
│   ├── safety-compliance/       # 3 skills
│   ├── vetting-risk/            # 4 skills
│   └── operations/              # 4 skills
├── scripts/
│   ├── validate.sh              # Single validator
│   └── setup-dev.sh             # Onboarding script
├── templates/                   # 6-doc enterprise planning templates
├── inventory/                   # Plugin + skill tracking CSVs
├── tests/                       # pytest suite
├── API-DISCOVERY.md             # Full API reference
├── MASTER-BLUEPRINT.md          # Architecture decisions
├── CHANGELOG.md
├── VERSION                      # 0.3.0
└── LICENSE                      # Apache-2.0

Contributing

Each plugin contains its own docs/ directory with a 6-document enterprise planning set (Business Case, PRD, Architecture, User Journey, Technical Spec, Status). Start there to understand the design intent before making changes.

Skills follow the /skill-creator specification. Required sections in every SKILL.md:

## Overview
## Prerequisites        (include API tier requirement)
## Instructions         (use {baseDir}/ for file references)
## Examples             (real freight scenarios)
## Error Handling
## Resources

Architecture Note

Versioned API adapters + evidence-driven skills.

The MCP servers own authentication, version routing, response normalization, tier gates, and deterministic operations such as batch checkpoints, policy-rule evaluation, and report rendering. The shared API contract keeps v3, v2, and v1 capabilities explicit and makes unknown parameters fail visibly.

The skills define the operational decision: which evidence to fetch, how to separate API facts from policy and inference, how missing data affects the result, and which person owns the next action. Named qualifications preserve SearchCarriers Pass/Review/Fail evidence; local vetting requires a complete caller-owned policy.

License

This project is licensed under the Apache License 2.0.

Apache-2.0 governs this repository's code. Calls to the hosted SearchCarriers API remain subject to the service's account requirements, subscription tiers, and terms.

Copyright (c) 2026 Intent Solutions, LLC. All rights reserved.