https://github.com/sheffieldp/hubspot_mcp
https://github.com/sheffieldp/hubspot_mcp
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/sheffieldp/hubspot_mcp
- Owner: SheffieldP
- License: mit
- Created: 2025-03-19T18:18:22.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-03-19T23:19:02.000Z (7 months ago)
- Last Synced: 2025-06-17T13:11:35.285Z (4 months ago)
- Language: Python
- Homepage: https://hubspot-mcp.vercel.app
- Size: 44.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HubSpot MCP Server
[](https://hub.docker.com/r/buryhuang/mcp-hubspot) [](https://smithery.ai/server/mcp-hubspot/prod)
## Overview
A Model Context Protocol (MCP) server implementation that provides integration with HubSpot CRM. This server enables AI models to interact with HubSpot data and operations through a standardized interface.
For more information about the Model Context Protocol and how it works, see [Anthropic's MCP documentation](https://www.anthropic.com/news/model-context-protocol).
## Components
### Resources
The server exposes the following resources:
* `hubspot://hubspot_contacts`: A dynamic resource that provides access to HubSpot contacts
* `hubspot://hubspot_companies`: A dynamic resource that provides access to HubSpot companies
* `hubspot://hubspot_recent_engagements`: A dynamic resource that provides access to HubSpot engagements from the last 3 days
All resources auto-update as their respective objects are modified in HubSpot.
### Example Prompts
- Create Hubspot contacts by copying from LinkedIn profile webpage:
```
Create HubSpot contacts and companies from following:
John Doe
Software Engineer at Tech Corp
San Francisco Bay Area • 500+ connections
Experience
Tech Corp
Software Engineer
Jan 2020 - Present · 4 yrs
San Francisco, California
Previous Company Inc.
Senior Developer
2018 - 2020 · 2 yrs
Education
University of California, Berkeley
Computer Science, BS
2014 - 2018
```
- Get latest activities for your company:
```
What's happening latestly with my pipeline?
```
### Tools
The server offers several tools for managing HubSpot objects:
#### Contact Management Tools
* `hubspot_get_contacts`
* Retrieve contacts from HubSpot
* No input required
* Returns: Array of contact objects
* `hubspot_create_contact`
* Create a new contact in HubSpot (checks for duplicates before creation)
* Input:
* `firstname` (string): Contact's first name
* `lastname` (string): Contact's last name
* `email` (string, optional): Contact's email address
* `properties` (dict, optional): Additional contact properties
* Example: `{"phone": "123456789", "company": "HubSpot"}`
* Behavior:
* Checks for existing contacts with the same first name and last name
* If `company` is provided in properties, also checks for matches with the same company
* Returns existing contact details if a match is found
* Creates new contact only if no match is found
#### Company Management Tools
* `hubspot_get_companies`
* Retrieve companies from HubSpot
* No input required
* Returns: Array of company objects
* `hubspot_create_company`
* Create a new company in HubSpot (checks for duplicates before creation)
* Input:
* `name` (string): Company name
* `properties` (dict, optional): Additional company properties
* Example: `{"domain": "example.com", "industry": "Technology"}`
* Behavior:
* Checks for existing companies with the same name
* Returns existing company details if a match is found
* Creates new company only if no match is found
* `hubspot_get_company_activity`
* Get activity history for a specific company
* Input:
* `company_id` (string): HubSpot company ID
* Returns: Array of activity objects
#### Engagement Tools
* `hubspot_get_recent_engagements`
* Get HubSpot engagements from all companies and contacts from the last 3 days
* No input required
* Returns: Array of engagement objects with full metadata
## Multi-User Support
This MCP server is designed to work with multiple HubSpot users, each with their own access token. The server does not use a global environment variable for the access token.
Instead, each request to the MCP server should include the user's specific access token in one of the following ways:
1. In the request header: `X-HubSpot-Access-Token: your-token-here`
2. In the request body as `accessToken`: `{"accessToken": "your-token-here"}`
3. In the request body as `hubspotAccessToken`: `{"hubspotAccessToken": "your-token-here"}`
This design allows you to store user tokens in your own backend (e.g., Supabase) and pass them along with each request.
### Example Multi-User Integration
```javascript
// Example of how to use this MCP server in a multi-user setup
async function makeHubSpotRequest(userId, action, params) {
// Retrieve the user's HubSpot token from your database
const userToken = await getUserHubSpotToken(userId);
// Make request to MCP server with the user's token
const response = await fetch('https://your-mcp-server.vercel.app/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-HubSpot-Access-Token': userToken
},
body: JSON.stringify({
action,
...params
})
});
return await response.json();
}
```
## Setup
### Prerequisites
You'll need a HubSpot access token for each user. You can obtain this by:
1. Creating a private app in your HubSpot account:
Follow the [HubSpot Private Apps Guide](https://developers.hubspot.com/docs/guides/apps/private-apps/overview)
- Go to your HubSpot account settings
- Navigate to Integrations > Private Apps
- Click "Create private app"
- Fill in the basic information:
- Name your app
- Add description
- Upload logo (optional)
- Define required scopes:
- oauth (required)
- Optional scopes:
- crm.dealsplits.read_write
- crm.objects.companies.read
- crm.objects.companies.write
- crm.objects.contacts.read
- crm.objects.contacts.write
- crm.objects.deals.read
- Review and create the app
- Copy the generated access token
Note: Keep your access token secure and never commit it to version control.
### Docker Installation
You can either build the image locally or pull it from Docker Hub. The image is built for the Linux platform.
#### Supported Platforms
- Linux/amd64
- Linux/arm64
- Linux/arm/v7
#### Option 1: Pull from Docker Hub
```bash
docker pull buryhuang/mcp-hubspot:latest
```
#### Option 2: Build Locally
```bash
docker build -t mcp-hubspot .
```
Run the container:
```bash
docker run \
buryhuang/mcp-hubspot:latest
```
## Cross-Platform Publishing
To publish the Docker image for multiple platforms, you can use the `docker buildx` command. Follow these steps:
1. **Create a new builder instance** (if you haven't already):
```bash
docker buildx create --use
```
2. **Build and push the image for multiple platforms**:
```bash
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-hubspot:latest --push .
```
3. **Verify the image is available for the specified platforms**:
```bash
docker buildx imagetools inspect buryhuang/mcp-hubspot:latest
```
## Usage with Claude Desktop
### Installing via Smithery
To install mcp-hubspot for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-hubspot/prod):
```bash
npx -y @smithery/cli@latest install mcp-hubspot --client claude
```
### Docker Usage
```json
{
"mcpServers": {
"hubspot": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"buryhuang/mcp-hubspot:latest"
]
}
}
}
```
## Development
To set up the development environment:
```bash
pip install -e .
```
## License
This project is licensed under the MIT License.