mcp-reports-server

MCP Reports Server

A comprehensive Model Context Protocol (MCP) server for generating various business reports with intelligent data presentation. This server provides multiple report types and AI-driven presentation suggestions to help you analyze and visualize your business data effectively.

🚀 Features

📊 Multiple Report Types

• Sales Reports - Revenue, orders, performance metrics
• User Analytics - Engagement, retention, behavior analysis
• Financial Reports - Profit/loss, expenses, financial health

🤖 AI-Driven Intelligence

• Smart Report Selection - LLM automatically chooses relevant reports based on your query
• Dynamic Presentation - AI suggests optimal data visualization (tables, charts, downloads)
• Contextual Insights - Automated analysis and recommendations

🎨 Flexible Data Presentation

• Tables - Structured data display with formatting
• Charts - Bar, line, pie, and scatter plot configurations
• Downloads - CSV, JSON, and Excel export options

📦 Installation

From npm (Recommended)

npm install -g mcp-reports-server

From source

git clone https://github.com/yourusername/mcp-reports-server.git
cd mcp-reports-server
npm install

🛠️ Usage

Running the Server

mcp-reports-server

Available Tools

1. smart_report_selector 🧠

Intelligently select and run multiple reports based on natural language queries.

Parameters:

• query (string): Describe what reports you need (e.g., "Show me sales and user data for last month")
• timeframe (string): Time period (e.g., "last 30 days", "this quarter")
• filters (object): Additional filters to apply

Example:

await callTool('smart_report_selector', {
  query: "I need to see our sales performance and user engagement for the last quarter",
  timeframe: "last 90 days"
});

2. sales_report 💰

Generate comprehensive sales reports with revenue and performance metrics.

Parameters:

• timeframe (string): Time period for analysis
• groupBy (string): How to group data (day, week, month, quarter, year, product, category, region)
• metrics (array): Which metrics to include (revenue, orders, average_order_value, units_sold, conversion_rate)
• filters (object): Additional filters (product_category, region, customer_segment, min_order_value)

Example:

await callTool('sales_report', {
  timeframe: "last 30 days",
  groupBy: "day",
  metrics: ["revenue", "orders", "average_order_value"],
  filters: { product_category: "Electronics" }
});

3. user_analytics_report 👥

Generate user engagement and analytics reports.

Parameters:

• timeframe (string): Time period for analysis
• metrics (array): User metrics (active_users, new_users, retention_rate, session_duration, page_views, bounce_rate)
• segmentation (string): How to segment users (age_group, location, device_type, acquisition_channel)

Example:

await callTool('user_analytics_report', {
  timeframe: "last 30 days",
  metrics: ["active_users", "retention_rate", "session_duration"],
  segmentation: "device_type"
});

4. financial_report 💼

Generate financial reports including profit/loss and expense analysis.

Parameters:

• timeframe (string): Time period for financial analysis
• reportType (string): Type of report (profit_loss, cash_flow, balance_sheet, expense_analysis)
• currency (string): Currency for the report

Example:

await callTool('financial_report', {
  timeframe: "this quarter",
  reportType: "profit_loss",
  currency: "USD"
});

5. format_as_table 📋

Format any data as a structured table for display.

Parameters:

• data (array): Array of data objects to format
• title (string): Table title
• columns (array): Column definitions

Example:

await callTool('format_as_table', {
  data: reportData,
  title: "Sales Performance Summary",
  columns: [
    { key: "date", label: "Date", type: "date" },
    { key: "revenue", label: "Revenue", type: "number" }
  ]
});

6. format_as_chart 📈

Format data as chart configuration for visualization.

Parameters:

• data (array): Data for chart
• chartType (string): Type of chart (bar, line, pie, scatter)
• title (string): Chart title
• xAxis (string): X-axis field
• yAxis (string): Y-axis field

Example:

await callTool('format_as_chart', {
  data: salesData,
  chartType: "line",
  title: "Revenue Trend",
  xAxis: "date",
  yAxis: "revenue"
});

7. prepare_download 💾

Prepare data for download in various formats.

Parameters:

• data (array): Data to prepare for download
• format (string): Download format (csv, json, excel)
• filename (string): Suggested filename

Example:

await callTool('prepare_download', {
  data: reportData,
  format: "csv",
  filename: "sales_report_2024"
});

🔧 MCP Configuration

Using npm package (Recommended)

Add to your MCP client configuration:

{
  "mcpServers": {
    "reports": {
      "command": "mcp-reports-server",
      "args": [],
      "env": {},
      "disabled": false,
      "autoApprove": [
        "smart_report_selector",
        "sales_report",
        "user_analytics_report", 
        "financial_report",
        "format_as_table",
        "format_as_chart",
        "prepare_download"
      ]
    }
  }
}

Using npx

{
  "mcpServers": {
    "reports": {
      "command": "npx",
      "args": ["--yes", "mcp-reports-server"],
      "env": {},
      "disabled": false
    }
  }
}

Using uvx (Alternative)

{
  "mcpServers": {
    "reports": {
      "command": "uvx",
      "args": ["mcp-reports-server"],
      "env": {},
      "disabled": false
    }
  }
}

🎯 Example Workflows

1. Comprehensive Business Overview

// Get intelligent report selection
const overview = await callTool('smart_report_selector', {
  query: "Give me a complete business overview including sales, users, and financials",
  timeframe: "last 30 days"
});

// Format key metrics as a table
await callTool('format_as_table', {
  data: overview.results[0].data.data,
  title: "Key Business Metrics"
});

// Create trend charts
await callTool('format_as_chart', {
  data: overview.results[0].data.data,
  chartType: "line",
  title: "Revenue Trend"
});

2. Sales Performance Analysis

// Get detailed sales report
const salesReport = await callTool('sales_report', {
  timeframe: "last 90 days",
  groupBy: "week",
  metrics: ["revenue", "orders", "average_order_value"]
});

// Visualize as bar chart
await callTool('format_as_chart', {
  data: salesReport.data,
  chartType: "bar",
  title: "Weekly Sales Performance",
  xAxis: "period",
  yAxis: "revenue"
});

// Prepare for download
await callTool('prepare_download', {
  data: salesReport.data,
  format: "excel",
  filename: "sales_analysis_q4_2024"
});

3. User Engagement Dashboard

// Get user analytics
const userReport = await callTool('user_analytics_report', {
  timeframe: "last 30 days",
  metrics: ["active_users", "new_users", "retention_rate"],
  segmentation: "device_type"
});

// Create pie chart for device distribution
await callTool('format_as_chart', {
  data: userReport.data,
  chartType: "pie",
  title: "Users by Device Type"
});

🔍 Data Structure Examples

Sales Report Output

{
  "reportType": "sales_report",
  "timeframe": "last 30 days",
  "summary": {
    "revenue": {
      "total": 450000,
      "average": 15000,
      "trend": "increasing"
    }
  },
  "data": [
    {
      "date": "2024-01-01",
      "revenue": 15000,
      "orders": 150,
      "average_order_value": 100
    }
  ],
  "insights": [
    {
      "type": "positive",
      "message": "Revenue is trending upward"
    }
  ]
}

Chart Configuration Output

{
  "type": "chart",
  "chartType": "line",
  "title": "Revenue Trend",
  "data": [
    { "x": "2024-01-01", "y": 15000, "label": "Jan 1", "value": 15000 }
  ],
  "config": {
    "xAxis": { "field": "date", "label": "Date" },
    "yAxis": { "field": "revenue", "label": "Revenue" }
  }
}

🚀 Advanced Features

Smart Query Processing

The smart_report_selector tool uses intelligent keyword matching to automatically select relevant reports:

• "sales revenue last month" → Runs sales_report
• "user engagement analytics" → Runs user_analytics_report
• "financial performance" → Runs financial_report
• "complete business overview" → Runs multiple reports

Automatic Presentation Suggestions

Each report includes AI-generated suggestions for optimal data presentation:

• Tables for detailed data review
• Line charts for trends over time
• Bar charts for comparisons
• Pie charts for proportional data
• Download options for further analysis

Extensible Architecture

Easy to add new report types by implementing the report interface:

export class CustomReport {
    constructor() {
        this.name = 'custom_report';
        this.description = 'Your custom report description';
        this.inputSchema = { /* schema definition */ };
    }
    
    async execute(params) {
        // Your report logic
        return reportData;
    }
}

🤝 Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Wiki

Made with ❤️ for the MCP community