jake/gusto-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Customize: Platform-specific README, tools, and docs

Browse Source
This commit is contained in:
Jake Shore 2026-02-02 06:58:04 -05:00
parent 595f68b3db
commit d4658fc0fc
3 changed files with 124 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.env.example
View File

@ -1,2 +1,3 @@
# Gusto API Credentials
GUSTO_API_KEY=your-api-key-here
# Get your OAuth token from: https://dev.gusto.com/
GUSTO_ACCESS_TOKEN=your-oauth-access-token-here

185
README.md
View File

@ -4,38 +4,47 @@
---
# 🚀 Gusto MCP Server — 2026 Complete Version
# 💼 Gusto MCP Server — HR & Payroll Intelligence
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Gusto workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**This MCP server gives AI direct access to your Gusto HR and payroll data.** Stop manually exporting spreadsheets or hunting through dashboards. Ask Claude questions in plain English, and get instant answers.
### 🎯 Gusto-Native Power Moves
### 🎯 Gusto-Specific Power Moves
The AI can directly control your Gusto account with natural language:
| Use Case | What It Does | Tools Used |
|----------|-------------|-----------|
| **Headcount reporting** | Get current employee list with salaries, departments, roles | `list_employees`, `get_employee` |
| **Payroll reconciliation** | Pull processed payrolls for a date range, verify amounts | `list_payrolls`, `get_payroll` |
| **Contractor audit** | List all 1099 contractors and YTD payments | `list_contractors` |
| **Benefits enrollment check** | See who's enrolled in health, 401k, etc. | `list_benefits`, `list_employees` |
| **Company info export** | Get all company details, locations, tax IDs | `get_company` |
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Gusto data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Gusto with other tools seamlessly
### 🔗 The Real Power: Natural Language HR Queries
### 🔗 The Real Power: Combining Tools
Instead of logging into Gusto and clicking around:
AI can chain multiple Gusto operations together:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- *"Show me all employees hired in the last 6 months"*
- *"What's our total payroll for Q4 2024?"*
- *"List all contractors with payments over $10k this year"*
- *"Who's enrolled in our health insurance plan?"*
- *"Get company details including all locations"*
## 📦 What's Inside
**91 API tools** covering the entire Gusto platform (HR & Payroll).
**7 HR-focused API tools** covering Gusto's core people operations:
All with proper error handling, automatic authentication, and TypeScript types.
- **Employees:** `list_employees`, `get_employee` — Staff directory, salaries, departments
- **Payroll:** `list_payrolls`, `get_payroll` — Pay runs, gross/net amounts, taxes
- **Contractors:** `list_contractors` — 1099 contractors and payments
- **Company:** `get_company` — Organization details, locations, settings
- **Benefits:** `list_benefits` — Health insurance, 401k, other benefits
All with OAuth2 bearer token authentication, proper error handling, and TypeScript types.
## 🚀 Quick Start
### Option 1: Claude Desktop (Local)
### Option 1: Claude Desktop (Recommended)
1. **Clone and build:**
```bash
@ -45,82 +54,116 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Gusto API credentials** (see Authentication section below)
2. **Get your Gusto OAuth token:**
- Log into [Gusto Developer Portal](https://dev.gusto.com/)
- Create a new application
- Complete the OAuth flow to get an **access token**
- **Note:** Gusto uses OAuth2, so you'll need to implement a refresh flow for production use
3. **Configure Claude Desktop:**
On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"gusto": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/gusto-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/gusto-mcp-2026-complete/dist/index.js"],
"env": {
"GUSTO_API_KEY": "your-api-key-here"
"GUSTO_ACCESS_TOKEN": "your-oauth-access-token"
}
}
}
}
```
4. **Restart Claude Desktop**
4. **Restart Claude Desktop** — you'll see 7 Gusto tools appear in the MCP section
### Option 2: Deploy to Railway
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/gusto-mcp)
1. Click the button above
2. Set your Gusto API credentials in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
### Option 2: Local Development
```bash
docker build -t gusto-mcp .
docker run -p 3000:3000 \
-e GUSTO_API_KEY=your-key \
gusto-mcp
cp .env.example .env
# Edit .env with your Gusto OAuth token
npm run dev
```
## 🔐 Authentication
See the official [Gusto API documentation](https://docs.gusto.com) for authentication details.
Gusto uses **OAuth2** for authentication:
The MCP server handles token refresh automatically.
1. Go to [Gusto Developer Portal](https://dev.gusto.com/)
2. Create a new **Partner Application**
3. Configure OAuth redirect URIs
4. Use the OAuth flow to obtain an **access token**
5. Set `GUSTO_ACCESS_TOKEN` in your environment
**Required Scopes:**
- `employees:read`
- `payrolls:read`
- `contractors:read`
- `company:read`
- `benefits:read`
**API Docs:** [https://docs.gusto.com/](https://docs.gusto.com/)
**⚠️ Token Expiration:** Access tokens expire after a certain period. For production, implement token refresh using Gusto's OAuth refresh flow.
## 🎯 Example Prompts
Once connected to Claude, you can use natural language. Examples:
Once connected to Claude:
- *"Show me recent activity in Gusto"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
**Employee Management:**
- *"List all employees in the Engineering department"*
- *"Show me details for employee ID abc123"*
- *"Who are our newest hires?"*
**Payroll Analysis:**
- *"Pull all processed payrolls from January 2025"*
- *"Show me payroll details for ID xyz789"*
- *"What's our average gross payroll per run?"*
**Contractor Management:**
- *"List all contractors"*
- *"Which contractors have YTD payments over $50k?"*
**Company & Benefits:**
- *"Get our company information"*
- *"What benefits do we offer?"*
- *"How many employees are enrolled in 401k?"*
## 🛠️ Development
### Prerequisites
- Node.js 18+
- npm or yarn
- Gusto account with API access
- Gusto account with API access (requires partner application setup)
### Setup
### Local Setup
```bash
git clone https://github.com/BusyBee3333/Gusto-MCP-2026-Complete.git
cd gusto-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Gusto credentials
# Edit .env with your OAuth token
npm run build
npm start
```
### Project Structure
```
gusto-mcp-2026-complete/
├── src/
│ └── index.ts # Main MCP server + Gusto API client
├── dist/ # Compiled JavaScript (npm run build)
├── package.json
├── tsconfig.json
└── .env.example
```
### Testing
```bash
@ -131,31 +174,43 @@ npm run test:coverage # Coverage report
## 🐛 Troubleshooting
### "Authentication failed"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "Gusto API error: 401 Unauthorized"
- Your access token is invalid or expired
- Generate a new token through the OAuth flow
- Verify you've set `GUSTO_ACCESS_TOKEN` correctly
### "Gusto API error: 403 Forbidden"
- Your OAuth application doesn't have the required scopes
- Check your app's permissions in the Gusto Developer Portal
### "Tools not appearing in Claude"
- Restart Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)
- Restart Claude Desktop after updating `claude_desktop_config.json`
- Verify the path is **absolute** (no `~` or relative paths)
- Check that `npm run build` completed successfully
- Look for the `dist/index.js` file
### "company_id required"
- Most Gusto API calls require a `company_id` parameter
- Get your company ID via the `get_company()` tool first
- Or find it in your Gusto dashboard URL
## 📖 Resources
- [Gusto API Documentation](https://docs.gusto.com)
- [Gusto API Documentation](https://docs.gusto.com/)
- [Gusto Developer Portal](https://dev.gusto.com/)
- [OAuth 2.0 Guide](https://docs.gusto.com/embedded-payroll/docs/oauth)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- [Claude Desktop Setup](https://claude.ai/desktop)
## 🤝 Contributing
Contributions are welcome! Please:
Contributions welcome! To add new Gusto API endpoints:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
5. Open a Pull Request
2. Add tool definitions to `src/index.ts` (tools array)
3. Implement handlers in `handleTool()` function
4. Update README with new capabilities
5. Submit a PR
## 📄 License
@ -163,10 +218,10 @@ MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
**Want more MCP servers?** Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms (Toast, Calendly, Stripe, QuickBooks, and more).
---
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

4
package.json
View File

@ -1,10 +1,10 @@
{
"name": "gusto-mcp-server",
"version": "1.0.0",
"description": "MCP server for Gusto API - 2026 Complete Version",
"description": "MCP server for Gusto - HR and payroll with 7 AI-ready tools",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",