quickbooks-mcp by richardbaxterseo - MCP Server

QuickBooks MCP Server (BETA)

⚠️ BETA SOFTWARE: This is beta software. Please test thoroughly in a sandbox environment before using with production data.

A Model Context Protocol (MCP) server that provides natural language access to QuickBooks financial data. Built with TypeScript and the node-quickbooks package.

🚀 Features

Profit & Loss Reports - Get P&L data with quarterly/monthly breakdowns
Company Information - Retrieve basic company details and settings
Financial Analysis - Natural language queries for financial data
Flexible Date Ranges - Query any time period
Detailed Breakdowns - Revenue by service type, expenses by category
Real-time Data - Current business transactions and balances

📋 Available Functions

`get_company_info`

Retrieves basic company information including name, address, fiscal year settings, and QuickBooks plan details.

Usage: "What's our company information?" or "Show me company details"

`get_profit_and_loss`

Generates Profit & Loss reports for specified date ranges with optional period breakdowns.

Parameters:

startDate (required): Start date in YYYY-MM-DD format
endDate (required): End date in YYYY-MM-DD format
summarizeColumnsByPeriod (optional): Boolean for quarterly/monthly breakdown

Usage Examples:

"Show me the P&L for Q1 2024"
"What's our annual P&L for 2024 with quarterly breakdown?"
"Generate a monthly P&L report for March 2025"

🛠️ Installation & Setup

Prerequisites

Node.js 16+ installed
QuickBooks Developer account
QuickBooks company (sandbox or production)

1. Clone and Install

git clone <repository-url>
cd quickbooks-mcp
npm install

2. Environment Setup

cp .env.example .env
# Edit .env with your QuickBooks API credentials

3. QuickBooks App Configuration

Create QuickBooks App:
- Visit QuickBooks Developer Console
- Create a new app
- Note your Client ID and Client Secret
OAuth Setup:
- Add redirect URI: https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl
- Use OAuth 2.0 Playground to obtain tokens
- Add tokens to your .env file

Environment Variables:

QB_CLIENT_ID=your_client_id_here
QB_CLIENT_SECRET=your_client_secret_here
QB_ACCESS_TOKEN=your_access_token_here
QB_REFRESH_TOKEN=your_refresh_token_here
QB_REALM_ID=your_company_realm_id_here
QB_ENVIRONMENT=sandbox  # or production
QB_BASE_URL=https://sandbox-quickbooks.api.intuit.com

4. Build and Test

npm run build
npm start

🖥️ Claude Desktop Integration

Local Configuration Setup

Copy example configuration:

cp claude-desktop-config.example.json claude-desktop-config.json

Update with your credentials: Edit claude-desktop-config.json and replace placeholder values with your actual QuickBooks API credentials.
Add to Claude Desktop: Copy the quickbooks server configuration from your local claude-desktop-config.json into your Claude Desktop configuration file.

⚠️ Security Note: Never commit claude-desktop-config.json - it contains sensitive API credentials and is excluded by .gitignore.

💬 Usage Examples

Once connected to Claude Desktop, you can ask natural language questions:

Financial Reports

"Show me the P&L for Q1 2024"
"What was our revenue in March 2025?"
"Generate an annual P&L for 2024 with quarterly breakdown"
"How did we perform financially this month?"
"What's our year-to-date profit and loss?"

Time Periods

"Show me this month's financial performance"
"Compare Q1 vs Q2 performance"
"What's our YTD revenue breakdown?"

🔧 Development

Development Mode

npm run dev  # Auto-reload during development

Build for Production

npm run build
npm start

Testing

# Test individual functions
node test-simple.mjs
node test-pl.mjs
node test-comprehensive.mjs

📁 Project Structure

quickbooks-mcp/
├── src/
│   └── index.ts              # Main MCP server implementation
├── dist/                     # Compiled JavaScript output
├── .env.example              # Environment variables template
├── .gitignore               # Git ignore rules
├── claude-desktop-config.example.json  # Claude Desktop config template
├── package.json             # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── TOKEN-MANAGEMENT.md     # Token refresh documentation
└── test-*.mjs              # Test scripts

🔒 Security Best Practices

API Key Management

✅ Use environment variables for all credentials
✅ Never commit API keys to version control
✅ Use .env files locally only
✅ Rotate tokens regularly as per QuickBooks guidelines
✅ Use sandbox environment for testing

File Protection

.env - Protected by .gitignore
claude-desktop-config.json - Protected by .gitignore
Only example/template files are committed

Token Management

Access tokens expire every 180 days
Refresh tokens expire every 101 days
See TOKEN-MANAGEMENT.md for refresh procedures

🚨 Beta Limitations

Limited Testing: Tested primarily with sandbox data
Error Handling: May need refinement for edge cases
Token Refresh: Manual token refresh required currently
Function Set: Additional QuickBooks endpoints planned
Production Use: Thorough testing recommended before production deployment

🗺️ Roadmap

Planned Features

Known Issues

Manual token refresh required every 180 days
Sandbox data may be limited for comprehensive testing

🤝 Contributing

This is beta software. Contributions welcome:

Test with your QuickBooks data
Report issues and edge cases
Suggest additional financial queries
Improve error handling
Add new QuickBooks API endpoints

📄 License

MIT License - see LICENSE file for details

📞 Support

Review TOKEN-MANAGEMENT.md for token issues
Check QuickBooks API documentation for data structure questions
Test in sandbox environment first
Verify all credentials are properly configured

⚠️ Remember: This is beta software. Always test thoroughly with sandbox data before connecting to production QuickBooks companies.