jake/gusto-mcp-2026-complete

Jake Shore d4658fc0fc Customize: Platform-specific README, tools, and docs

2026-02-02 06:58:04 -05:00

7.0 KiB

Raw Blame History

🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

💼 Gusto MCP Server — HR & Payroll Intelligence

💡 What This Unlocks

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-Specific Power Moves

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`

🔗 The Real Power: Natural Language HR Queries

Instead of logging into Gusto and clicking around:

"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

7 HR-focused API tools covering Gusto's core people operations:

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 (Recommended)

Clone and build:

git clone https://github.com/BusyBee3333/Gusto-MCP-2026-Complete.git
cd gusto-mcp-2026-complete
npm install
npm run build

Get your Gusto OAuth token:
- Log into Gusto Developer Portal
- 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

Configure Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gusto": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gusto-mcp-2026-complete/dist/index.js"],
      "env": {
        "GUSTO_ACCESS_TOKEN": "your-oauth-access-token"
      }
    }
  }
}

Restart Claude Desktop — you'll see 7 Gusto tools appear in the MCP section

Option 2: Local Development

cp .env.example .env
# Edit .env with your Gusto OAuth token
npm run dev

🔐 Authentication

Gusto uses OAuth2 for authentication:

Go to Gusto Developer Portal
Create a new Partner Application
Configure OAuth redirect URIs
Use the OAuth flow to obtain an access token
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/

⚠️ 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:

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 (requires partner application setup)

Local Setup

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 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

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

🐛 Troubleshooting

"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 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

🤝 Contributing

Contributions welcome! To add new Gusto API endpoints:

Fork the repo
Add tool definitions to src/index.ts (tools array)
Implement handlers in handleTool() function
Update README with new capabilities
Submit a PR

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms (Toast, Calendly, Stripe, QuickBooks, and more).

Questions? Open an issue or join our Discord community.

7.0 KiB Raw Blame History