# Mezmo MCP Server
A Model Context Protocol (MCP) server for retrieving logs from Mezmo. Quota-conscious design with intelligent defaults - just add your API key and run!
## ⚡ Smart Defaults
- **Time Range**: Last 6 hours (when not specified) - balances quota with finding actual logs
- **Log Count**: 10 logs per request
- **Log Levels**: All levels (you control filtering)
**Recommended Workflow**:
1. First, fetch 3-5 logs to discover available apps and log shape
2. Then, filter by specific app(s) you're debugging
3. Add level filtering for ERROR/WARNING to reduce noise
4. Increase count only after filters are in place (e.g., 20-50)
5. This approach minimizes quota usage significantly!
## 🚀 Quick Start
### 1. Get Your API Key
Get your Mezmo Service API key from the Mezmo dashboard.
### 2. Run with Docker
```bash
# Clone the repository
# (replace with your fork/clone URL)
git clone <your-repo-url>
cd <your-repo-dir>
# Create your local .env (never commit it)
cp env.example .env
# then edit .env and set MEZMO_API_KEY
# Build and run
docker-compose up -d
```
### 3. Configure Your MCP Client
**For Cursor** (add to `.cursor/mcp.json`):
```json
{
"mcpServers": {
"mezmo": {
"url": "http://localhost:18080/mcp",
"transport": "streamable-http",
"description": "Mezmo log retrieval"
}
}
}
```
**For Claude Desktop** (add to MCP settings):
```json
{
"mcpServers": {
"mezmo": {
"command": "docker",
"args": ["exec", "mezmo-mcp-server", "python", "server.py"]
}
}
}
```
### 4. Start Using
Restart your MCP client and you'll have access to the `get_logs` tool!
## 📋 Usage
The `get_logs` tool automatically retrieves logs from the **last 6 hours** when no time range is specified - perfect for debugging while conserving quota.
**Step 1: Discover available apps (3-5 logs):**
```json
{
"count": 3,
"levels": "ERROR,WARNING"
}
```
**Step 2: Filter by specific app:**
```json
{
"count": 10,
"apps": "app-a",
"levels": "ERROR,WARNING"
}
```
**Advanced filtering (scale up only after filters work):**
```json
{
"count": 50,
"apps": "app-a,app-b",
"levels": "ERROR,WARNING",
"query": "database connection"
}
```
**Custom time range (use sparingly - impacts quota):**
```json
{
"count": 50,
"apps": "app-a",
"from_ts": "1640995200",
"to_ts": "1640998800"
}
```
### 💡 Quota-Conscious Tips
1. **Always filter by app** when possible - this drastically reduces results
2. **Start tiny** - use count=3-5 for discovery, then increase if needed
3. **Add level filtering** - specify levels="ERROR,WARNING" to reduce noise
4. **Use default 6-hour window** unless you need wider historical data
### 🔐 Security / Secrets
- **Never commit `.env`** (it contains your `MEZMO_API_KEY`).
- Prefer using `.env.example` as a template and keep your real values local.
- If you enable MCP authentication (`MCP_ENABLE_AUTH=true`), keep `MCP_API_TOKEN` secret as well.
## 🛠️ Commands
```bash
docker-compose up -d # Start the server
docker-compose down # Stop the server
docker-compose logs -f # View logs
```
## 🐛 Troubleshooting
**Container won't start?**
- Check your `.env` file has `MEZMO_API_KEY=your_actual_key`
- View logs: `docker-compose logs`
**Can't connect from MCP client?**
- Ensure container is running: `docker-compose ps`
- Restart your MCP client after configuration changes
That's it! The server runs on port 18080 and automatically handles time windows, retries, and error handling.
