HubSpot Auditor

What HubSpot Auditor MCP server does

The HubSpot Auditor MCP server evaluates a HubSpot portal across CRM, pipelines, forms, tracking, email, reporting, brand, journey, and program configuration. Each check is classified as working, broken, or missing, with severity and supporting evidence. Evidence is limited to counts and names such as properties or deal stages; contact records are not printed.

The audit score is the percentage of checks that are working. Findings are organized into a remediation schedule: critical and high-severity broken items appear in the 30-day plan, medium broken items and critical or high missing items appear in the 60-day plan, and remaining items are assigned to 90 days.

Supported checks include duplicate contacts and companies, required properties, lifecycle data, deal and ticket pipelines, stale deals, forms, consent, spam protection, tracking, UTM capture, email authentication, workflows, subscription types, dashboards, attribution, landing-page metadata, and buyer-stage coverage.

How it works

In live mode, the server reads HubSpot through GET requests using a private app token. It does not send POST, PUT, PATCH, or DELETE requests, and the token is read from the environment rather than accepted as a tool argument. Missing read access produces a missing finding for the relevant area; throttling and server errors are reported separately rather than treated as missing permissions.

Demo mode reads the fictional Harbour Glass Co. portal from demo/portal.json, making it possible to inspect the workflow without a HubSpot token. Public-site checks require an HTTPS URL and reject destinations resolving to loopback, private, link-local, or CGNAT addresses. Redirect destinations are checked as well.

Rules are stored as versioned YAML files under rules/. Checks can be disabled with enabled: false, and thresholds are configured beneath params. Brand markers and buyer-stage patterns are also configured in these files.

Setup and configuration

The HubSpot Auditor MCP server requires Node.js 22 or newer. It can be started with npx -y hubspot-auditor, installed globally with npm, or built from a cloned repository. A demo audit can run without credentials:

npx -y hubspot-auditor --demo --out reports

For a live portal, create a HubSpot private app with read scopes only, export its token, and run the CLI or configure the MCP server with that environment variable:

export HUBSPOT_ACCESS_TOKEN="read-only-token"
hubspot-auditor --site https://example.com --summary

The --site value is used for tracking checks; if omitted, tracking uses the portal's primary site domain. Landing-page checks use the CMS page URL. Set HUBSPOT_AUDITOR_DOH=0 to disable the DNS-over-HTTPS fallback used when the system resolver cannot find api.hubapi.com.

Tools and capabilities

The MCP interface exposes two tools:

• list_checks returns the configured YAML checks, including severity and parameters.
• run_audit runs the audit with optional demo, publicSiteUrl, and pdfPath parameters.

run_audit can write a PDF under the reports/ directory when given a filename such as audit.pdf. The CLI can also produce Markdown and JSON reports. The server supports audit questions about critical findings, weak properties, deal-stage probabilities, email checks, and the generated 30/60/90-day plan.

The live audit requires scopes appropriate to the areas being checked, including CRM object and schema reads, company and deal reads, owner and list reads, forms, content, communication preferences, and automation. A missing scope affects only the corresponding checks. Webhook subscription edits and connected-app listing are not audited because those HubSpot endpoints do not provide that data for a private app.