Gripp

Model Context Protocol server for the Gripp API 3.0 endpoint at https://api.gripp.com/public/api3.php.

The Gripp API is JSON-RPC-like: requests are POSTed as a batch array, and the API token is sent as Authorization: Bearer <token>.

Setup

npm install
npm run fetch:metadata
npm run build

Set your Gripp API token before starting the server:

export GRIPP_API_TOKEN="your-token"
npm start

Optional environment variables:

GRIPP_API_URL=https://api.gripp.com/public/api3.php
GRIPP_REQUEST_TIMEOUT_MS=30000

GRIPP_API_URL is intentionally restricted to the https://api.gripp.com/ host.

MCP Client Config

Example stdio config:

{
  "mcpServers": {
    "gripp": {
      "command": "node",
      "args": ["/absolute/path/to/MCP Gripp/dist/src/cli.js"],
      "env": {
        "GRIPP_API_TOKEN": "your-token"
      }
    }
  }
}

After publishing or linking the package, you can also run the gripp-mcp binary.

Vercel Remote MCP

This repo also exposes a Streamable HTTP MCP endpoint for Vercel through a Next.js route:

https://your-vercel-domain.vercel.app/api/mcp

For Claude custom connectors, use the /api/mcp URL. The root URL only returns a health response.

Set this environment variable in Vercel before using Gripp tools:

GRIPP_API_TOKEN=your-token
MCP_ACCESS_KEY=long-random-secret

Use the access key in Claude's custom connector URL:

https://your-vercel-domain.vercel.app/api/mcp?access_key=long-random-secret

The /api/mcp endpoint fails closed in production if MCP_ACCESS_KEY is not set. If the URL leaks, rotate MCP_ACCESS_KEY in Vercel and redeploy.

The remote endpoint can also read a Gripp token from Authorization: Bearer <token> or x-gripp-api-token, but Claude's custom connector UI does not currently provide a simple custom-header field. For Claude, the practical setup is to store GRIPP_API_TOKEN in the Vercel project environment.

GoHighLevel Remote MCP

The same Vercel project can also host a GoHighLevel MCP endpoint with OAuth token storage:

https://your-vercel-domain.vercel.app/api/connect/mcp

Set these environment variables in Vercel:

GHL_CLIENT_ID=your-highlevel-client-id
GHL_CLIENT_SECRET=your-highlevel-client-secret
GHL_APP_ID=your-highlevel-app-or-version-id
GHL_INSTALL_URL=your-highlevel-installation-url
GHL_REDIRECT_URI=https://your-vercel-domain.vercel.app/api/connect/callback
GHL_OAUTH_USER_TYPE=Company
GHL_MCP_ACCESS_KEY=long-random-secret
GHL_TOKEN_ENCRYPTION_KEY=$(openssl rand -hex 32)
KV_REST_API_URL=your-upstash-or-vercel-kv-rest-url
KV_REST_API_TOKEN=your-upstash-or-vercel-kv-rest-token

UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN also work instead of the KV_* names.

In the HighLevel Marketplace app settings, add this redirect URL:

https://your-vercel-domain.vercel.app/api/connect/callback

Then open the OAuth start URL in your browser:

https://your-vercel-domain.vercel.app/api/connect/start

After HighLevel redirects back, the callback page stores that subaccount installation. Use one shared URL in Claude's custom connector screen:

https://your-vercel-domain.vercel.app/api/connect/mcp?access_key=long-random-secret

Install the app once per subaccount by reopening /api/connect/start and choosing the next location. The MCP keeps an index of all connected installations. In Claude, call ghl_list_installations first, then pass the chosen installId to the contact, opportunity, or generic API tools.

If your Marketplace app can only be installed by an agency admin, set GHL_OAUTH_USER_TYPE=Company. After installing once at agency level, use ghl_list_installed_locations to see where the app is actually installed, then ghl_connect_location to create a stored Location installation for the subaccount you want to query. ghl_list_locations only lists visible subaccounts and does not prove the app is installed on them.

The GoHighLevel MCP fails closed in production if GHL_MCP_ACCESS_KEY, encrypted token storage, or OAuth credentials are missing.

GoHighLevel Tools

• ghl_installation_status: show the OAuth installation metadata without exposing tokens.
• ghl_list_installations: list all connected subaccounts/installations.
• ghl_list_locations: list/search subaccounts from a connected agency/company install.
• ghl_list_installed_locations: list locations where this app is installed/authorized.
• ghl_connect_location: create and store a Location token from an agency/company install.
• ghl_get_contact: retrieve one contact by contact ID.
• ghl_search_contacts: search contacts with /contacts/search.
• ghl_create_contact: create a contact; requires confirm: true.
• ghl_update_contact: update a contact; requires confirm: true.
• ghl_search_opportunities: search opportunities with /opportunities/search.
• ghl_api_call: call any relative HighLevel API path; non-GET calls require confirm: true.

Tools

• gripp_list_entities: list available Gripp entities and method names.
• gripp_describe_entity: inspect fields, enum values, references, methods, and examples for one entity.
• gripp_get: call <entity>.get with filters and options.
• gripp_getone: call <entity>.getone with filters.
• gripp_create: call <entity>.create; requires confirm: true.
• gripp_update: call <entity>.update; requires confirm: true.
• gripp_delete: call <entity>.delete; requires confirm: true.
• gripp_call: call any documented Gripp method by full name.
• gripp_batch: execute multiple documented Gripp calls in one transaction.

Non-read methods are blocked unless confirm: true is provided. This also applies to gripp_call and each item in gripp_batch.

Examples

Find companies by name:

{
  "entity": "company",
  "filters": [
    {
      "field": "company.companyname",
      "operator": "like",
      "value": "%Acme%"
    }
  ],
  "options": {
    "paging": {
      "firstresult": 0,
      "maxresults": 10
    },
    "orderings": [
      {
        "field": "company.companyname",
        "direction": "asc"
      }
    ]
  }
}

Call a nonstandard read method:

{
  "method": "company.getCompanyByCOC",
  "params": ["12345678"]
}

Create a tag:

{
  "entity": "tag",
  "fields": {
    "name": "Imported"
  },
  "confirm": true
}

Metadata

The committed metadata snapshot is generated from the public API docs page:

npm run fetch:metadata

Refresh it when Gripp updates the API docs.