MCP server for querying MCP Observatory metrics
npm install @lukrlier/mcp-observatory-serverbash
npm install -g @lukrlier/mcp-observatory-server
`
$3
`bash
cd packages/mcp-server
pnpm install
pnpm build
`
Quick Start
$3
Add to your claude_desktop_config.json:
File DataSource (Standalone):
`json
{
"mcpServers": {
"mcp-observatory": {
"command": "mcp-observatory-server",
"args": ["--file", "/path/to/metrics.ndjson"]
}
}
}
`
From source:
`json
{
"mcpServers": {
"mcp-observatory": {
"command": "node",
"args": [
"/path/to/mcp-observatory/packages/mcp-server/dist/index.js",
"--file",
"/path/to/metrics.ndjson"
]
}
}
}
`
$3
Restart Claude Desktop and ask:
- "What are the metrics for my MCP server?"
- "Show me slow tools in the last hour"
- "Are there any errors I should know about?"
Data Sources
$3
Reads metrics from local NDJSON file. Perfect for standalone monitoring.
`bash
mcp-observatory-server --file ./metrics.ndjson --debug
`
Configuration:
`json
{
"command": "mcp-observatory-server",
"args": ["--file", "/path/to/metrics.ndjson", "--debug"]
}
`
Use Cases:
- Local development
- Self-hosted monitoring
- No external dependencies
- 95% of use cases
$3
Reads metrics from PostgreSQL database. For production deployments.
`bash
mcp-observatory-server --postgres "postgresql://localhost:5432/mcp"
`
Configuration:
`json
{
"command": "mcp-observatory-server",
"args": ["--postgres", "postgresql://user:pass@host:5432/db"]
}
`
Use Cases:
- Production environments
- Multi-server monitoring
- Long-term storage
- Advanced queries
Status: Coming soon
$3
Connects to hosted MCP Observatory service.
`bash
mcp-observatory-server --cloud sk_xxx
`
Configuration:
`json
{
"command": "mcp-observatory-server",
"args": ["--cloud", "sk_your_api_key"]
}
`
Use Cases:
- Team collaboration
- Centralized dashboard
- Multi-server monitoring
- Optional hosted service
Status: Coming soon
CLI Arguments
| Argument | Description | Example |
| ------------------ | ---------------------- | ----------------------------- |
| --file | File data source | --file ./metrics.ndjson |
| --postgres | PostgreSQL data source | --postgres postgresql://... |
| --cloud | Cloud data source | --cloud sk_xxx |
| --debug | Enable debug logging | --debug |
Priority: --file > --postgres > --cloud > environment variables
Available Tools
New in v1.0.1: All tools now support optional server_id parameter. When omitted, they return aggregated metrics across all your MCP servers.
$3
Get real-time performance metrics for an MCP server.
Parameters:
- server_id (optional): MCP server identifier - if not provided, returns aggregated metrics for all servers
- time_range (optional): 5m, 1h, 24h, 7d, 30d (default: 1h)
Returns:
`json
{
"serverId": "srv_xxx",
"timeRange": "1h",
"totalCalls": 1543,
"successRate": 0.987,
"avgDuration": 145,
"p50": 120,
"p95": 280,
"p99": 450,
"errorRate": 0.013,
"topTools": [
{
"toolName": "get_weather",
"calls": 456,
"avgDuration": 123
}
]
}
`
Example:
`
"Show me the performance metrics for my server in the last 24 hours"
`
$3
Get detailed statistics for a specific tool.
Parameters:
- server_id (optional): MCP server identifier - if not provided, returns stats across all servers
- tool_name (required): Name of the tool to analyze
- time_range (optional): Time range (default: 1h)
Returns:
`json
{
"serverId": "srv_xxx",
"toolName": "get_weather",
"timeRange": "24h",
"totalCalls": 456,
"successCount": 448,
"errorCount": 8,
"avgDuration": 123,
"p50": 110,
"p95": 245,
"p99": 389
}
`
Example:
`
"What are the statistics for the get_weather tool?"
`
$3
Retrieve recent error logs for debugging.
Parameters:
- server_id (optional): MCP server identifier - if not provided, returns errors from all servers
- limit (optional): Maximum errors to return (default: 50, max: 100)
- severity (optional): Filter by severity level - all, error, critical (default: all)
Returns:
`json
{
"serverId": "srv_xxx",
"errors": [
{
"id": "evt_xxx",
"timestamp": 1766162308300,
"errorType": "ValidationError",
"message": "Invalid city parameter",
"stack": "Error: Invalid city parameter..."
}
],
"total": 23
}
`
Example:
`
"Show me the recent errors from my server"
`
$3
Calculate estimated API costs for a server.
Parameters:
- server_id (optional): MCP server identifier - if not provided, returns costs for all servers
- time_range (optional): Time range (default: 24h)
Returns:
`json
{
"serverId": "srv_xxx",
"timeRange": "24h",
"totalCalls": 1543,
"estimatedCost": 0.0154,
"costPerCall": 0.00001
}
`
Example:
`
"What are the estimated costs for my server this week?"
`
$3
AI-powered performance analysis with actionable recommendations.
Parameters:
- server_id (optional): MCP server identifier - if not provided, analyzes all servers
- time_range (optional): Time range (default: 24h)
Returns:
`json
{
"serverId": "srv_xxx",
"timeRange": "24h",
"insights": [
{
"type": "slow_tool",
"severity": "high",
"toolName": "search_web",
"message": "Tool is significantly slower than average",
"avgDuration": 567,
"recommendation": "Consider optimizing or implementing caching"
}
],
"healthScore": 0.85
}
`
Example:
`
"Analyze the performance of my server and give me recommendations"
`
Development
$3
`bash
pnpm build
`
$3
`bash
pnpm dev
`
$3
`bash
node dist/index.js --file ./metrics.ndjson --debug
`
$3
`bash
pnpm test
`
Architecture
`
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā Your MCP Server ā
ā āā Instrumented with @lukrlier/mcp-observatory-sdk ā
ā āā Events ā FileReporter ā metrics.ndjson ā
ā ā
āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā MCP Observatory Server (this package) ā
ā āā FileDataSource reads metrics.ndjson ā
ā āā Exposes 5 MCP tools for querying metrics ā
ā ā
āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā Claude Desktop ā
ā āā User asks: "What are my server metrics?" ā
ā āā Claude calls get_server_metrics tool ā
ā āā Claude responds with natural language insights ā
ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
`
Examples
See examples/basic-file-reporter for a complete working example.
Advanced Usage
$3
`typescript
import { DataSource, ObservatoryServer } from '@lukrlier/mcp-observatory-server';
class CustomDataSource implements DataSource {
async getServerMetrics(params: MetricsQueryParams): Promise {
// Custom implementation
}
async getToolStats(params: ToolStatsQueryParams): Promise {
// Custom implementation
}
// ... other methods
}
const dataSource = new CustomDataSource();
const server = new ObservatoryServer({ dataSourceConfig: {...} }, dataSource);
`
Troubleshooting
$3
1. Check claude_desktop_config.json syntax
2. Verify absolute paths are correct
3. Restart Claude Desktop completely
4. Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\
$3
1. Verify file path is absolute, not relative
2. Check file permissions
3. Ensure SDK has created the file first
4. Enable debug mode: --debug
$3
1. Verify server_id matches SDK configuration (or omit to query all servers)
2. Check time range is valid
3. Ensure events have been written to file
4. Check file contains valid NDJSON
$3
New in v1.0.1: You can monitor multiple MCP servers and query them all at once without specifying server_id:
`
User: "What are my overall server metrics?"
Claude: Calls get_server_metrics() without server_id
Returns aggregated metrics + per-server breakdown
`
This is useful for:
- Getting an overview of all your MCP servers
- Comparing performance across different servers
- Identifying which server has issues
$3
1. Enable debug mode: --debug
2. Check Claude Desktop developer tools
3. Verify data source is accessible
4. Check file format is valid NDJSON
TypeScript Support
Full TypeScript support with type definitions included.
`typescript
import type {
DataSource,
ObservatoryServer,
ServerMetrics,
ToolStats,
ErrorLogsResponse,
} from '@lukrlier/mcp-observatory-server';
``