diff --git a/.env.example b/.env.example index 4ba1f76..c0acb1b 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index 6c7fb10..63c4e20 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/package.json b/package.json index 115e5df..499691a 100644 --- a/package.json +++ b/package.json @@ -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 ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",