Content
# Grow MCP Server
Bring AI-powered analytics to your Grow account. This MCP (Model Context Protocol) server enables Claude to fetch, analyze, and derive insights from your Grow dashboards in real-time.
## Features
✨ **Core Capabilities**
- 📊 Fetch dashboard data and metrics in seconds
- 📈 Analyze trends and spot anomalies
- 🎯 Get account summaries at a glance
- 🚨 Monitor alert status across metrics
- 💾 Smart caching to minimize API calls
- 🔍 Deep-dive analysis with date ranges and comparisons
✅ **Built for Scale**
- Zero dependencies on external services
- Runs locally on your machine
- Fully free (uses your existing Grow account)
- Works seamlessly with Claude.ai
---
## Quick Start
### 1. Installation
```bash
npm install @your-username/grow-mcp
```
### 2. Setup
Create a `.env` file in your project root:
```env
GROW_API_KEY=your_grow_api_key_here
GROW_API_BASE_URL=https://api.growapp.io
LOG_LEVEL=info
CACHE_TTL=300
```
**How to get your Grow API key:**
1. Log into Grow (grow.com)
2. Go to **Settings** → **API**
3. Generate a new API key
4. Copy and paste into `.env`
### 3. Run the Server
```bash
grow-mcp start
```
You should see:
```
✓ Grow MCP Server started on port 3000
✓ Connected to Grow API
✓ Ready to accept connections
```
---
## Usage Examples
### With Claude.ai
Once the server is running, you can ask Claude things like:
**Quick Analytics**
```
"Show me a summary of my Grow account"
```
**Drill-Down Analysis**
```
"What was the revenue trend for the last 30 days? Did any metrics spike or drop?"
```
**Anomaly Detection**
```
"Analyze my metrics from last week. Which ones changed the most?"
```
**Dashboard Health**
```
"Which of my dashboards haven't been updated recently?"
```
**Comparative Analysis**
```
"Compare my revenue across regions. Which one is performing best?"
```
### Programmatic Usage
```typescript
import { GrowMCPServer } from '@your-username/grow-mcp';
const server = new GrowMCPServer({
apiKey: process.env.GROW_API_KEY,
cacheTtl: 300
});
// Get account summary
const summary = await server.getAccountSummary();
console.log(summary);
// Get metrics for date range
const metrics = await server.getMetrics({
dateFrom: '2025-02-12',
dateTo: '2025-03-12',
limit: 50
});
// Analyze trends
const trends = await server.analyzeTrend({
metricName: 'revenue',
dateFrom: '2025-02-12',
dateTo: '2025-03-12',
anomalyThreshold: 0.2
});
```
---
## Available Tools
### `getAccountSummary`
Get a quick overview of your Grow account.
**Returns:**
- Active dashboards count
- Total metrics count
- Last updated timestamp
- Account health status
**Example:**
```
Claude: "Give me a summary of my account"
```
---
### `listDashboards`
List all dashboards in your Grow account.
**Parameters:**
- `limit` (optional): Max dashboards to return (default: 100)
- `offset` (optional): Pagination offset (default: 0)
**Returns:**
```json
{
"dashboards": [
{
"id": "dashboard-123",
"name": "Sales Dashboard",
"description": "Q1 2025 sales metrics",
"last_updated": "2025-03-12T14:30:00Z",
"metrics_count": 12
}
],
"total": 5,
"timestamp": "2025-03-12T15:45:00Z"
}
```
---
### `getDashboard`
Fetch detailed data from a specific dashboard.
**Parameters:**
- `dashboardId` (required): ID of the dashboard
- `includeHistory` (optional): Include historical data (default: false)
**Returns:**
```json
{
"dashboard": {
"id": "dashboard-123",
"name": "Sales Dashboard",
"metrics": [
{
"id": "metric-1",
"name": "Total Revenue",
"value": 145000,
"unit": "USD",
"trend": "up",
"change_pct": 12.5,
"last_updated": "2025-03-12T14:30:00Z"
}
]
}
}
```
---
### `getMetrics`
Fetch metrics for a specific date range.
**Parameters:**
- `dateFrom` (required): Start date (YYYY-MM-DD)
- `dateTo` (required): End date (YYYY-MM-DD)
- `metricNames` (optional): Filter by specific metrics
- `limit` (optional): Max metrics to return (default: 100)
**Returns:**
```json
{
"metrics": [
{
"name": "Revenue",
"value": 145000,
"date": "2025-03-12",
"change_vs_previous_period": 12.5,
"change_vs_last_year": 18.3
}
],
"period": "2025-02-12 to 2025-03-12"
}
```
---
### `getAlerts`
Get the status of all alerts in your account.
**Returns:**
```json
{
"alerts": [
{
"id": "alert-1",
"metric": "Revenue",
"threshold": 100000,
"current_value": 145000,
"status": "active",
"triggered_at": "2025-03-12T14:30:00Z"
}
],
"active_count": 2,
"total_count": 8
}
```
---
### `analyzeTrend`
Advanced trend analysis with anomaly detection.
**Parameters:**
- `metricName` (required): Name of metric to analyze
- `dateFrom` (required): Start date
- `dateTo` (required): End date
- `anomalyThreshold` (optional): Deviation % to flag as anomaly (default: 0.2)
**Returns:**
```json
{
"metric": "Revenue",
"trend": "up",
"data_points": 30,
"anomalies": [
{
"date": "2025-03-08",
"value": 95000,
"deviation_pct": -34.5,
"note": "Weekend drop"
}
],
"stats": {
"min": 85000,
"max": 150000,
"average": 122000,
"std_dev": 18500
},
"recommendation": "Revenue is trending up with normal weekend fluctuations. Consider investigating the dip on 2025-03-08."
}
```
---
## Configuration
### Environment Variables
```env
# Required
GROW_API_KEY=your_api_key_here
# Optional
GROW_API_BASE_URL=https://api.growapp.io
LOG_LEVEL=info # debug, info, warn, error
CACHE_TTL=300 # Cache time-to-live in seconds
CACHE_MAX_SIZE=1000 # Max number of cached items
TIMEOUT=30000 # Request timeout in ms
```
### Programmatic Config
```typescript
const server = new GrowMCPServer({
apiKey: process.env.GROW_API_KEY,
baseUrl: 'https://api.growapp.io',
cacheTtl: 300,
cacheMaxSize: 1000,
timeout: 30000,
logLevel: 'info'
});
```
---
## How It Works
```
┌─────────────────────────────────────────┐
│ Claude.ai (Your Chat) │
│ │
│ "Analyze my revenue last 30 days" │
└──────────────┬──────────────────────────┘
│
│ Sends request via MCP
▼
┌─────────────────────────────────────────┐
│ Grow MCP Server (Your Machine) │
│ │
│ 1. Parse request │
│ 2. Check cache (5 min TTL) │
│ 3. Call Grow API if needed │
│ 4. Analyze data │
│ 5. Return structured response │
└──────────────┬──────────────────────────┘
│
│ Returns insights
▼
┌─────────────────────────────────────────┐
│ Claude responds with insights │
│ │
│ "Revenue up 12% YoY. Anomaly on 3/8" │
└─────────────────────────────────────────┘
```
---
## Development
### Prerequisites
- Node.js 18+
- npm or yarn
- Grow account with API access
### Setup Dev Environment
```bash
git clone https://github.com/your-username/grow-mcp.git
cd grow-mcp
npm install
cp .env.example .env
# Edit .env with your Grow API key
npm run dev
```
### Running Tests
```bash
# Run all tests
npm test
# Watch mode
npm test -- --watch
# With UI
npm run test:ui
```
### Type Checking
```bash
npm run type-check
```
### Building for Production
```bash
npm run build
npm start
```
---
## Architecture
### Caching Strategy
- **Dashboards:** 30 minutes (rarely change)
- **Metrics:** 5 minutes (update frequency varies)
- **Alerts:** 1 minute (should be current)
- Manual cache invalidation available
### Error Handling
- Graceful fallback if API is unreachable
- Clear error messages for invalid requests
- Automatic retry for transient failures
- Logs all errors for debugging
### Performance
- Batch API calls when possible
- Compress responses
- Paginate large datasets
- Minimal memory footprint
---
## Troubleshooting
### "API Key Invalid"
```
❌ Error: Invalid API key
```
**Solution:**
1. Go to Grow Settings → API
2. Verify your API key is correct
3. Update `.env` file
4. Restart the server
### "Connection Timeout"
```
❌ Error: Request timeout after 30s
```
**Solution:**
1. Check your internet connection
2. Verify Grow API is online (status.growapp.io)
3. Increase timeout: `TIMEOUT=60000`
4. Check logs: `LOG_LEVEL=debug`
### "No Metrics Returned"
```
❌ Error: No data for date range
```
**Solution:**
1. Verify the date range has data in Grow
2. Check metric names are spelled correctly
3. Ensure your Grow account has active metrics
### Enable Debug Logging
```bash
LOG_LEVEL=debug npm run dev
```
This will show all API calls and cached responses.
---
## Contributing
We welcome contributions! Here's how:
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Add tests
5. Run `npm test` to verify
6. Commit: `git commit -m 'Add amazing feature'`
7. Push: `git push origin feature/amazing-feature`
8. Open a Pull Request
### Areas for Contribution
- [ ] Add more analysis tools (forecasting, segmentation)
- [ ] Improve caching strategy
- [ ] Add support for Grow alerts creation
- [ ] Performance optimizations
- [ ] Better error messages
- [ ] Expanded documentation
---
## Roadmap
### v1.0 (Current)
- ✅ Account summary
- ✅ Dashboard listing
- ✅ Metrics fetching
- ✅ Alert monitoring
- ✅ Trend analysis
### v1.1 (Planned)
- 📅 Forecast predictions
- 📊 Segment comparisons
- 🔔 Alert creation (write support)
- 📱 Mobile-friendly outputs
### v2.0 (Future)
- 🤖 Custom anomaly detection
- 🎯 Goal tracking
- 📧 Email integration
- 🔄 Automated reporting
---
## FAQ
**Q: Does this cost money?**
A: No! The MCP server is free. You only need your existing Grow account.
**Q: Does my data leave my machine?**
A: No. The server runs locally and only communicates with Grow's API using your API key.
**Q: Can I use this without Claude?**
A: Yes! You can use it programmatically or as a CLI tool.
**Q: How often does data refresh?**
A: By default, data is cached for 5 minutes. You can adjust `CACHE_TTL` or manually refresh.
**Q: Is my API key secure?**
A: Yes. It's stored locally in `.env` and never shared. Keep `.env` in `.gitignore`.
**Q: Can I contribute?**
A: Absolutely! See the [Contributing](#contributing) section.
---
## License
MIT © 2025 Your Name
---
## Support
- 📖 [Full Documentation](./docs/README.md)
- 🐛 [Report Issues](https://github.com/your-username/grow-mcp/issues)
- 💬 [GitHub Discussions](https://github.com/your-username/grow-mcp/discussions)
- 📧 Email: your-email@example.com
---
## Changelog
### v1.0.0 (2025-03-12)
- Initial release
- Core tools implemented
- Documentation complete
- Published to npm
---
**Made with ❤️ for the Grow community**
⭐ If this helps you, please star the repo!
