BQE Core MCP Server

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with BQE Core API data. Access your projects, time entries, invoices, and more through natural language queries.

Quick Start

No installation needed! Claude Desktop will automatically download and run the server using npx.

Configuration

1. Get your BQE OAuth credentials:

   • Go to the BQE Developer Portal
   • Click "Add New Application"
   • Fill in the application details:
     • Application Name: BQE Core MCP Server (or anything else you like)
     • Application Type: Regular Web App
     • Redirect URI: http://localhost:8765/callback
     • Description: (any description you like, e.g., "Claude Desktop Integration")
   • Save your Client ID and Client Secret for Step 2

2. Configure Claude Desktop:

   Edit your Claude Desktop configuration file:

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

   You can also locate this file by going to the Developer tab of Claude Desktop and clicking Edit Config.

   {
     "mcpServers": {
       "bqe-core": {
         "command": "npx",
         "args": ["bqe-core-mcp"],
         "env": {
           "BQE_CLIENT_ID": "your_client_id_here",
           "BQE_CLIENT_SECRET": "your_client_secret_here"
         }
       }
     }
   }

3. Restart Claude Desktop

4. Authenticate:

   • In Claude, type: "authenticate with BQE Core"
   • Your browser will open for OAuth login
   • Authorize the application
   • Return to Claude when complete

Features

• 🔐 Secure Authentication: OAuth 2.0 with tokens stored in macOS Keychain
• 📊 Comprehensive Data Access: Projects, clients, time entries, invoices, payments, and more
• ⚡ Optimized Performance: Lightweight tools that reduce token usage by up to 90%
• 🔄 Smart Rate Limiting: Automatic throttling and retry logic
• 🧮 Advanced Analytics: Business intelligence tools for profitability, cash flow, and trends

Example Queries

Project Management

• "Show me all my active projects"
• "What's the status of the Morgan Stanley project?"
• "Show me the health dashboard for Project ABC"
• "Which projects need immediate attention?"

Time & Billing

• "What's ready to bill for ABC Corp?"
• "Show me my unbilled time entries this month"
• "How many billable hours did I work last week?"
• "What expenses are unbilled for Project XYZ?"

Financial Analysis

• "Who owes us money? Show accounts receivable"
• "Who are our top 5 clients by revenue this year?"
• "How profitable is Client ABC?"
• "Show me October's financial summary"
• "Which clients pay the fastest?"
• "I received a check for $25,509.02 from Morgan Stanley"

Client Management

• "Find the client ID for Morgan Stanley"
• "Show me all contacts for ABC Corp"
• "Get a complete summary of our relationship with XYZ Inc"
• "Which clients have paid us the most?"

Available Tools

Core Resources

• Projects: List, search, and analyze project data
• Clients & Contacts: Access client information and relationships
• Time Tracking: Review time entries and utilization
• Expenses: Track project and employee expenses
• Invoices & Payments: Monitor billing and collections
• Vendors & Bills: View vendor relationships (payment status in external systems)

Analytical Tools

• Project Health Dashboard: Comprehensive project status and warnings
• Client Profitability: Analyze profit margins and costs by client
• Payment Velocity: Track how quickly invoices get paid
• Monthly Financial Summary: Complete monthly metrics and trends
• Billing Readiness: See what's ready to invoice immediately
• Top Clients by Revenue: Cash-basis revenue rankings

Lightweight Tools

These tools are optimized to use 90% fewer tokens:

• getClientIdByName - Quick client lookup
• getClientList - Browse all clients efficiently
• getProjectIdsByClient - List projects with minimal data
• getOverdueInvoiceSummary - Statistical summary without details

Important Notes

Prerequisites

• macOS (required for Keychain integration)
• Node.js 18 or higher
• BQE Core account with API access

Known Limitations

Invoice Analysis: The invoice list API doesn't include client information, limiting accrual-based revenue analysis. Use getTopClientsByCashRevenue for cash-basis analytics instead.

Bill Payments: This organization tracks vendor payments in Ramp, not BQE Core. All bills appear as "unpaid" in BQE Core regardless of actual status.

Statistical Analysis: The API doesn't support server-side aggregation (SUM, AVG, COUNT). Complex analytics require fetching all data, which may exceed token limits.

Troubleshooting

Authentication Issues

• Ensure OAuth redirect URI is exactly http://localhost:8765/callback
• Verify Client ID and Secret are correct
• Try "logout" then "authenticate" again

Rate Limits

• The server handles rate limiting automatically
• If you see persistent errors, reduce request frequency
• Check rate limit status in tool responses

Connection Problems

• Verify internet connectivity
• Check BQE Core service status
• Ensure firewall allows outbound HTTPS

Support

For issues or questions:

1. Check the troubleshooting section above
2. Visit BQE Core API documentation
3. Report issues at: https://bitbucket.org/spice-labs/bqe-core-mcp/issues

Development

For developers who want to contribute or run from source:

Installation from Source

git clone https://bitbucket.org/spice-labs/bqe-core-mcp.git
cd bqe-core-mcp
npm install
npm run build

Environment Setup

Create a .env file:

BQE_CLIENT_ID=your_client_id_here
BQE_CLIENT_SECRET=your_client_secret_here

Claude Desktop Configuration (Development)

{
  "mcpServers": {
    "bqe-core": {
      "command": "node",
      "args": ["/absolute/path/to/bqe-core-mcp/dist/index.js"],
      "env": {
        "BQE_CLIENT_ID": "your_client_id_here",
        "BQE_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Development Commands

npm run dev        # Run in development mode
npm run build      # Build TypeScript
npm run lint       # Run ESLint
npm run typecheck  # Type checking

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - See LICENSE