# HubSpot Auditor [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/M-Pineapple/hubspot-auditor  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hubspot-auditor

## Description
Read-only MCP server that audits a HubSpot portal: what works, what is broken, what is missing.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "hubspot-auditor": {
    "command": "npx",
    "args": ["-y","hubspot-auditor"],
    "env": {
      "HUBSPOT_ACCESS_TOKEN": "",
      "HUBSPOT_AUDITOR_DOH": ""
    }
  }
}
```

**Requires environment variables:** `HUBSPOT_ACCESS_TOKEN`, `HUBSPOT_AUDITOR_DOH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/hubspot-auditor/readme_