HubSpot MCP Server

Instructions

🎯 Purpose
  1. Authenticates and analyzes the current HubSpot access token, providing context about the user's permissions and account details.

🧭 Usage Guidance:
  1. This tool must be used before performing any operations with Hubspot tools to determine the identity of the user, and permissions they have on their Hubspot account.

📦 Returns:
  1. User ID, Hub ID, App ID, token type, a comprehensive list of authorized API scopes, and detailed owner information, and account information.
  2. The uiDomain and hubId can be used to construct URLs to the HubSpot UI for the user.
  3. If the user is an owner, the ownerId will help identify objects that are owned by the user.

Implementation Reference

• dist/tools/oauth/getUserDetailsTool.js:31-82 (handler)

  UserCredentialsTool class implementing the tool handler logic. Fetches HubSpot token info, owner details, and account info using the HubSpotClient and returns formatted text content.

  export class UserCredentialsTool extends BaseTool {
      client;
      constructor() {
          super(TokenInfoSchema, ToolDefinition);
          this.client = new HubSpotClient();
      }
      // Implement the process method
      async process(_args) {
          const accessToken = process.env.PRIVATE_APP_ACCESS_TOKEN || process.env.HUBSPOT_ACCESS_TOKEN;
          if (!accessToken) {
              return {
                  content: [
                      {
                          type: 'text',
                          text: 'Error: PRIVATE_APP_ACCESS_TOKEN not found in environment variables',
                      },
                  ],
                  isError: true,
              };
          }
          try {
              const [tokenInfo, accountInfo] = await Promise.all([
                  this.client.post('/oauth/v2/private-apps/get/access-token-info', {
                      body: { tokenKey: accessToken },
                  }),
                  this.client.get('/account-info/v3/details').catch(() => null),
              ]);
              const ownerInfo = await this.client
                  .get(`/crm/v3/owners/${tokenInfo.userId}?idProperty=userId&archived=false`)
                  .catch(() => null);
              return {
                  content: [
                      { type: 'text', text: '- Token Info: ' + JSON.stringify(tokenInfo, null, 2) },
                      { type: 'text', text: '- OwnerInfo: ' + JSON.stringify(ownerInfo, null, 2) },
                      { type: 'text', text: '- AccountInfo: ' + JSON.stringify(accountInfo, null, 2) },
                  ],
              };
          }
          catch (error) {
              return {
                  content: [
                      {
                          type: 'text',
                          text: `Error retrieving token, owner, and account information. ${error instanceof Error ? error.message : String(error)}
              `,
                      },
                  ],
                  isError: true,
              };
          }
      }
  }

• dist/tools/oauth/getUserDetailsTool.js:6-29 (schema)

  Zod input schema (empty object, no params) and ToolDefinition with name, description, inputSchema converted to JSON schema, and annotations.

  const TokenInfoSchema = z.object({});
  const ToolDefinition = {
      name: 'hubspot-get-user-details',
      description: `
      🎯 Purpose
        1. Authenticates and analyzes the current HubSpot access token, providing context about the user's permissions and account details.
  
      🧭 Usage Guidance:
        1. This tool must be used before performing any operations with Hubspot tools to determine the identity of the user, and permissions they have on their Hubspot account.
  
      📦 Returns:
        1. User ID, Hub ID, App ID, token type, a comprehensive list of authorized API scopes, and detailed owner information, and account information.
        2. The uiDomain and hubId can be used to construct URLs to the HubSpot UI for the user.
        3. If the user is an owner, the ownerId will help identify objects that are owned by the user.
    `,
      inputSchema: zodToJsonSchema(TokenInfoSchema),
      annotations: {
          title: 'Get User Details',
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
      },
  };

• dist/tools/toolsRegistry.js:4-27 (registration)

  Import of UserCredentialsTool and registration via registerTool(new UserCredentialsTool()); in the tools registry.

  import { UserCredentialsTool } from './oauth/getUserDetailsTool.js';
  import { ObjectListTool } from './objects/listObjectsTool.js';
  import { ObjectSearchTool } from './objects/searchObjectsTool.js';
  import { BatchCreateAssociationsTool } from './associations/batchCreateAssociationsTool.js';
  import { AssociationSchemaDefinitionTool } from './associations/getAssociationDefinitionsTool.js';
  import { AssociationsListTool } from './associations/listAssociationsTool.js';
  import { BatchCreateObjectsTool } from './objects/batchCreateObjectsTool.js';
  import { BatchUpdateObjectsTool } from './objects/batchUpdateObjectsTool.js';
  import { BatchReadObjectsTool } from './objects/batchReadObjectsTool.js';
  import { PropertiesListTool } from './properties/listPropertiesTool.js';
  import { GetPropertyTool } from './properties/getPropertyTool.js';
  import { CreatePropertyTool } from './properties/createPropertyTool.js';
  import { UpdatePropertyTool } from './properties/updatePropertyTool.js';
  import { CreateEngagementTool } from './engagements/createEngagementTool.js';
  import { GetEngagementTool } from './engagements/getEngagementTool.js';
  import { UpdateEngagementTool } from './engagements/updateEngagementTool.js';
  import { FeedbackLinkTool } from './links/feedbackLinkTool.js';
  import { GetSchemasTool } from './objects/getSchemaTool.js';
  import { GetHubspotLinkTool } from './links/getHubspotLinkTool.js';
  import { WorkflowsListTool } from './workflows/listWorkflowsTool.js';
  import { GetWorkflowTool } from './workflows/getWorkflowTool.js';
  import { RefreshTokenTool } from './oauth/refreshTokenTool.js';
  // Register all tools
  registerTool(new UserCredentialsTool());