@eugeneboondock/hubspot-mcp-server 0.2.15

package/Dockerfile

@@ -0,0 +1,22 @@
+FROM node:22.12-alpine AS builder
+
+COPY . /app
+
+WORKDIR /app
+
+RUN npm install
+
+FROM node:22-alpine AS release
+
+WORKDIR /app
+
+COPY --from=builder /app/build /app/build
+COPY --from=builder /app/package.json /app/package.json
+COPY --from=builder /app/package-lock.json /app/package-lock.json
+
+ENV NODE_ENV=production
+
+
+RUN npm ci --ignore-scripts --omit-dev
+EXPOSE 8080
+ENTRYPOINT ["npx", "mcp-proxy", "node", "/app/dist/index.js"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 peakmojo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# HubSpot MCP Server
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.9.5-blue.svg)](https://www.typescriptlang.org/)
+[![HubSpot API](https://img.shields.io/badge/HubSpot%20API-v3-orange.svg)](https://developers.hubspot.com/docs/api/overview)
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.8.0-green.svg)](https://github.com/modelcontextprotocol/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A powerful Model Context Protocol (MCP) server implementation for seamless HubSpot CRM integration, enabling AI assistants to interact with your HubSpot data.
+
+## Overview
+
+This MCP server provides a comprehensive set of tools for interacting with the HubSpot CRM API, allowing AI assistants to:
+
+- Create and manage contacts and companies in your HubSpot CRM
+- Retrieve detailed company activity history and engagement timelines
+- Access recent engagement data across your entire HubSpot instance
+- Get lists of recently active companies and contacts
+- Search for tasks and notes with advanced filtering
+- Perform CRM operations without leaving your AI assistant interface
+
+## Why Use This MCP Server?
+
+- **Seamless AI Integration**: Connect your AI assistants directly to your HubSpot CRM data
+- **Simplified CRM Operations**: Perform common HubSpot tasks through natural language commands
+- **Real-time Data Access**: Get up-to-date information from your HubSpot instance
+- **Secure Authentication**: Uses HubSpot's OAuth token authentication
+- **Extensible Design**: Easily add more HubSpot API capabilities as needed
+- **Magic Card Integration**: Supports Morphed Magic Card detection and processing
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/lkm1developer/hubspot-mcp-server.git
+cd hubspot-mcp-server
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Configuration
+
+The server requires a HubSpot API access token. You can obtain one by:
+
+1. Going to your [HubSpot Developer Account](https://developers.hubspot.com/)
+2. Creating a private app with the necessary scopes (contacts, companies, engagements, tasks, notes)
+3. Copying the generated access token
+
+You can provide the token in two ways:
+
+1. As an environment variable:
+   ```
+   HUBSPOT_ACCESS_TOKEN=your-access-token
+   ```
+
+2. As a command-line argument:
+   ```
+   npm start -- --access-token=your-access-token
+   ```
+
+For development, create a `.env` file in the project root to store your environment variables:
+
+```
+HUBSPOT_ACCESS_TOKEN=your-access-token
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+# Start the server
+npm start
+
+# Or with a specific access token
+npm start -- --access-token=your-access-token
+
+# Run the SSE server with authentication
+npx mcp-proxy-auth node dist/index.js
+```
+
+### Implementing Authentication in SSE Server
+
+The SSE server uses the [mcp-proxy-auth](https://www.npmjs.com/package/mcp-proxy-auth) package for authentication. To implement authentication:
+
+1. Install the package:
+   ```bash
+   npm install mcp-proxy-auth
+   ```
+
+2. Set the `AUTH_SERVER_URL` environment variable to point to your API key verification endpoint:
+   ```bash
+   export AUTH_SERVER_URL=https://your-auth-server.com/verify
+   ```
+
+3. Run the SSE server with authentication:
+   ```bash
+   npx mcp-proxy-auth node dist/index.js
+   ```
+
+4. The SSE URL will be available at:
+   ```
+   localhost:8080/sse?apiKey=apikey
+   ```
+
+   Replace `apikey` with your actual API key for authentication.
+
+The `mcp-proxy-auth` package acts as a proxy that:
+- Intercepts requests to your SSE server
+- Verifies API keys against your authentication server
+- Only allows authenticated requests to reach your SSE endpoint
+
+### Integrating with AI Assistants
+
+This MCP server is designed to work with AI assistants that support the Model Context Protocol. Once running, the server exposes a set of tools that can be used by compatible AI assistants to interact with your HubSpot CRM data.
+
+### Available Tools
+
+The server exposes the following powerful HubSpot integration tools:
+
+1. **hubspot_create_contact**
+   - Create a new contact in HubSpot with duplicate checking
+   - Parameters:
+     - `firstname` (string, required): Contact's first name
+     - `lastname` (string, required): Contact's last name
+     - `email` (string, optional): Contact's email address
+     - `properties` (object, optional): Additional contact properties like company, phone, etc.
+
+2. **hubspot_create_company**
+   - Create a new company in HubSpot with duplicate checking
+   - Parameters:
+     - `name` (string, required): Company name
+     - `properties` (object, optional): Additional company properties
+
+3. **hubspot_get_company_activity**
+   - Get comprehensive activity history for a specific company
+   - Parameters:
+     - `companyId` (string, required): HubSpot company ID
+   - Returns detailed engagement data including emails, calls, meetings, notes, and tasks
+
+4. **hubspot_get_recent_engagements**
+   - Get recent engagement activities across all contacts and companies
+   - Parameters:
+     - `days` (number, optional, default: 7): Number of days to look back
+     - `limit` (number, optional, default: 50): Maximum number of engagements to return
+
+5. **hubspot_get_active_companies**
+   - Get most recently active companies from HubSpot
+   - Parameters:
+     - `limit` (number, optional, default: 10): Maximum number of companies to return
+
+6. **hubspot_get_active_contacts**
+   - Get most recently active contacts from HubSpot
+   - Parameters:
+     - `limit` (number, optional, default: 10): Maximum number of contacts to return
+
+7. **hubspot_get_deals**
+   - Get deals from HubSpot with comprehensive properties
+   - Parameters:
+     - `limit` (number, optional, default: 10): Maximum number of deals to return
+
+8. **hubspot_get_tickets**
+   - Get support tickets from HubSpot
+   - Parameters:
+     - `limit` (number, optional, default: 10): Maximum number of tickets to return
+
+9. **hubspot_get_orders**
+   - Get ecommerce orders from HubSpot
+   - Parameters:
+     - `limit` (number, optional, default: 10): Maximum number of orders to return
+
+10. **hubspot_get_current_user**
+    - Get authenticated user info and portal details
+    - No parameters required
+
+11. **hubspot_search_tasks**
+    - Search for tasks with advanced filtering
+    - Parameters:
+      - `searchTerm` (string, optional): Text to search for in task content
+      - `modifiedAfter` (string, optional): ISO date string to filter by modification date
+
+12. **hubspot_search_notes**
+    - Search for notes with advanced filtering
+    - Parameters:
+      - `searchTerm` (string, optional): Text to search for in note content
+      - `modifiedAfter` (string, optional): ISO date string to filter by modification date
+
+13. **hubspot_update_contact**
+    - Update an existing contact in HubSpot (ignores if contact does not exist)
+    - Parameters:
+      - `contact_id` (string, required): HubSpot contact ID to update
+      - `properties` (object, required): Contact properties to update
+
+14. **hubspot_update_company**
+    - Update an existing company in HubSpot (ignores if company does not exist)
+    - Parameters:
+      - `company_id` (string, required): HubSpot company ID to update
+      - `properties` (object, required): Company properties to update
+
+## Extending the Server
+
+The server is designed to be easily extensible. To add new HubSpot API capabilities:
+
+1. Add new methods to the `HubSpotClient` class in `src/hubspot-client.ts`
+2. Register new tools in the `setupToolHandlers` method in `src/index.ts`
+3. Rebuild the project with `npm run build`
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Keywords
+
+HubSpot, CRM, Model Context Protocol, MCP, AI Assistant, TypeScript, API Integration, HubSpot API, CRM Integration, Contact Management, Company Management, Engagement Tracking, AI Tools, Magic Cards

package/dist/auth-client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Authentication client for MCP server
+ * Handles custom API key validation and OAuth token retrieval
+ */
+interface APIKeyValidationResponse {
+    valid: boolean;
+    portal_id: string;
+    key_name: string;
+    scopes: string[];
+    authenticated_at: string;
+}
+export declare class AuthClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    /**
+     * Validate the MCP API key and get portal context
+     */
+    validateAPIKey(): Promise<APIKeyValidationResponse>;
+    /**
+     * Get OAuth token for the portal associated with this API key
+     */
+    getOAuthToken(): Promise<string>;
+    /**
+     * Get portal ID associated with this API key
+     */
+    getPortalId(): Promise<string>;
+}
+export {};

package/dist/auth-client.js

@@ -0,0 +1,76 @@
+/**
+ * Authentication client for MCP server
+ * Handles custom API key validation and OAuth token retrieval
+ */
+export class AuthClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl || process.env.MORPHED_API_URL || 'https://morphed.io';
+    }
+    /**
+     * Validate the MCP API key and get portal context
+     */
+    async validateAPIKey() {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/mcp/validate`, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            if (!response.ok) {
+                throw new Error(`API key validation failed: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            console.error('API key validation failed:', error);
+            throw new Error(`Failed to validate API key: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get OAuth token for the portal associated with this API key
+     */
+    async getOAuthToken() {
+        try {
+            // First validate the API key to get portal context
+            const validation = await this.validateAPIKey();
+            if (!validation.valid) {
+                throw new Error('Invalid API key');
+            }
+            // Get OAuth token for the portal
+            const response = await fetch(`${this.baseUrl}/api/mcp/oauth/token?portalId=${validation.portal_id}`, {
+                method: 'GET',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json'
+                }
+            });
+            if (!response.ok) {
+                throw new Error(`OAuth token fetch failed: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            if (!data.success || !data.data.access_token) {
+                throw new Error('No OAuth token available for this portal');
+            }
+            console.log(`Retrieved OAuth token for portal ${validation.portal_id}`);
+            return data.data.access_token;
+        }
+        catch (error) {
+            console.error('OAuth token retrieval failed:', error);
+            throw new Error(`Failed to get OAuth token: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get portal ID associated with this API key
+     */
+    async getPortalId() {
+        const validation = await this.validateAPIKey();
+        return validation.portal_id;
+    }
+}
+//# sourceMappingURL=auth-client.js.map

package/dist/auth-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-client.js","sourceRoot":"","sources":["../src/auth-client.ts"],"names":[],"mappings":"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"}

package/dist/hubspot-client.d.ts

@@ -0,0 +1,88 @@
+export declare function convertDatetimeFields(obj: any): any;
+export declare class HubSpotScopeError extends Error {
+    scope: string;
+    code: string;
+    constructor(scopeName: string, cause?: any);
+}
+export declare class HubSpotClient {
+    private client;
+    private accessToken;
+    private lastRequestTime;
+    private requestCount;
+    private rateLimitWindow;
+    constructor(accessToken?: string);
+    /**
+     * Update the access token and reinitialize the client
+     */
+    updateAccessToken(newToken: string): void;
+    /**
+     * Wrapper for API calls with automatic token refresh on 401 errors
+     */
+    private callWithRetry;
+    /**
+     * Rate limiting to prevent 429 errors
+     */
+    private rateLimitDelay;
+    /**
+     * Helper method to paginate through all results using HubSpot's after cursor
+     */
+    private paginateSearch;
+    private normalizeDateInput;
+    private applyUpdatedAfterFilter;
+    /**
+     * Helper method to paginate through all results using HubSpot's after cursor (for List/GET APIs)
+     */
+    private paginateList;
+    getRecentCompanies(limit?: number, updatedAfter?: string): Promise<any>;
+    getRecentContacts(limit?: number, updatedAfter?: string): Promise<any>;
+    getAssociations(fromObjectType: string, fromObjectId: string, toObjectType: string): Promise<any[]>;
+    searchTasks(minutes?: number, limit?: number): Promise<any>;
+    searchNotes(minutes?: number, limit?: number): Promise<any>;
+    searchCalls(minutes?: number, limit?: number): Promise<any>;
+    searchEmails(minutes?: number, limit?: number): Promise<any>;
+    searchMeetings(minutes?: number, limit?: number): Promise<any>;
+    getRecentEngagements(limit?: number): Promise<any>;
+    createContact(firstname: string, lastname: string, email?: string, properties?: Record<string, any>): Promise<any>;
+    createCompany(name: string, properties?: Record<string, any>): Promise<any>;
+    createNote(body: string, associations?: any[]): Promise<any>;
+    updateContact(contactId: string, properties: Record<string, any>): Promise<any>;
+    updateCompany(companyId: string, properties: Record<string, any>): Promise<any>;
+    getRecentDeals(limit?: number, updatedAfter?: string): Promise<any>;
+    getCurrentUser(): Promise<any>;
+    getRecentTickets(limit?: number): Promise<any>;
+    getRecentOrders(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getOrders(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getContactById(contactId: string): Promise<any>;
+    getCompanyById(companyId: string): Promise<any>;
+    getDealById(dealId: string): Promise<any>;
+    getTicketById(ticketId: string): Promise<any>;
+    private handleOptionalScopeError;
+    getForms(limit?: number): Promise<any[]>;
+    getFormSubmissions(formId: string, limit?: number): Promise<any[]>;
+    getMarketingEmails(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getEmailEvents(limit?: number): Promise<any[]>;
+    getCampaigns(limit?: number): Promise<any[]>;
+    getAnalytics(startDate: string, endDate: string): Promise<any>;
+    getBlogPosts(limit?: number): Promise<any[]>;
+    getLandingPages(limit?: number): Promise<any[]>;
+    getKnowledgeBase(limit?: number): Promise<any[]>;
+    getPipelines(objectType?: string): Promise<any[]>;
+    getProperties(objectType: string): Promise<any[]>;
+    getQuotes(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getUsers(limit?: number): Promise<any[]>;
+    getOwners(limit?: number): Promise<any[]>;
+    getConversations(limit?: number): Promise<any[]>;
+    getCalls(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getMeetings(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getCustomObjects(objectType?: string, limit?: number): Promise<any[]>;
+    getSitePages(limit?: number): Promise<any[]>;
+    getFiles(limit?: number): Promise<any[]>;
+    private fetchFilesSegment;
+    getHubDbTables(limit?: number): Promise<any[]>;
+    getProducts(limit?: number, updatedAfter?: string): Promise<any[]>;
+    getLineItems(limit?: number, updatedAfter?: string): Promise<any[]>;
+    searchObjects(objectType: string, query: string, limit?: number): Promise<any[]>;
+    getLists(limit?: number): Promise<any[]>;
+    getWorkflows(limit?: number): Promise<any[]>;
+    getDomains(limit?: number): Promise<any[]>;
+}