Lumenore Analytics MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with access to Lumenore's analytics and natural language query capabilities. Built with FastMCP and Python 3.13 for scalable data analytics integration.
Quick Start
1. Install & Run
git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your client credentials (LUMENORE_CLIENT_ID and LUMENORE_SECRET)
python main.py
2. Connect Your AI Assistant
- URL:
http://localhost:8080/mcp - Transport: Streamable HTTP
3. Start Analyzing
# Example: Get sales insights
result = await client.call_tool("nlq_to_data", {
"userQuery": "Top 5 sales regions last month",
"schemaId": 123
})
📖 Full Documentation | 🐛 Report Issues | 🔒 Privacy Policy
Table of Contents
- Overview
- Installation
- Configuration
- Available Tools
- Usage Examples
- Authentication
- Security & Privacy
- Troubleshooting
- Contributing
- Support
- License
Overview
This MCP server provides AI assistants with access to Lumenore's powerful analytics capabilities:
- Natural Language Queries: Convert questions to data insights
- Advanced Analytics: Trends, predictions, correlations, outliers, changes, Pareto analysis
- Real-time Processing: Stream responses for large datasets
- Zero Data Storage: In-memory processing with no persistent logging. When the MCP Server forwards requests to Lumenore's backend, Lumenore's privacy policies apply
Installation
Prerequisites
- Python 3.13+
- Lumenore client credentials (client ID and secret)
- Access to Lumenore server instance
Setup
git clone https://github.com/Lumenore-Platform/lumenore-mcp.git
cd lumenore-mcp
pip install -r requirements.txt
Configuration
Create a .env file in the project root with your credentials. You can use .env.example as a template:
cp .env.example .env
Then edit .env with your configuration:
Using Client Credentials
LUMENORE_CLIENT_ID="your_client_id_here"
LUMENORE_SECRET="your_secret_here"
SERVER_URL="https://preview.lumenore.com"
Configuration Parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
LUMENORE_CLIENT_ID | Yes | Client ID for client credentials authentication | None |
LUMENORE_SECRET | Yes | Client secret for client credentials authentication | None |
SERVER_URL | No | Lumenore server URL | https://preview.lumenore.com |
Running the Server
Start the MCP server:
python main.py
The server runs on http://0.0.0.0:8080 with SSE transport for real-time streaming.
Connecting Your AI Assistant
Claude for Desktop
- Settings → MCP Servers
- Add Server with:
Name: Lumenore Analytics URL: http://localhost:8080/mcp Transport: Streamable HTTP
Programmatic Access (Python)
from mcp.client import MCPClient
client = MCPClient("http://localhost:8080/mcp", transport="streamable_http")
tools = await client.list_tools()
result = await client.call_tool("nlq_to_data", {
"userQuery": "Top 5 sales regions last month",
"schemaId": 123
})
Connection Details:
- Protocol: MCP 2024-11-05+
- Transport: Streamable HTTP (SSE)
- Port: 8080 (default)
- Auth: No MCP-level auth required
Test Connection:
curl -I http://localhost:8080 # Should return HTTP/1.1 200 OK
Authentication
Getting Your Credentials
Client Credentials
- Contact Lumenore support to obtain client credentials
- Receive your
LUMENORE_CLIENT_IDandLUMENORE_SECRET - Store securely in your
.envfile
See the Configuration section for detailed setup instructions.
Security Best Practices
Troubleshooting Authentication Issues
"Authorization token missing or invalid":
- Verify credentials are set in
.envfile:- For client credentials: Check both
LUMENORE_CLIENT_IDandLUMENORE_SECRETare set
- For client credentials: Check both
- Ensure Lumenore AI credits are available
- Check
SERVER_URLpoints to correct Lumenore instance
Available Tools
The server provides 8 powerful tools for data analysis:
Dataset Management
get_dataset_metadata - Lists available datasets and schema IDs
Natural Language Queries
nlq_to_data - Converts questions to structured data
{
"userQuery": "Top 5 sales regions last month",
"schemaId": 123
}
Advanced Analytics
get_trend_data - Identifies temporal patterns and trends
get_prediction_data - Generates forecasts and predictions
get_outlier_data - Detects anomalies and unusual patterns
get_correlation_data - Analyzes variable relationships
get_change_data - Detects pattern shifts and transitions
get_pareto_data - Performs 80/20 impact analysis
Error Handling
All tools return standardized responses:
- Success:
{"data": {...}, "status": "success"} - Validation Error:
{"error": "...", "status": "validation_error"} - Service Error:
{"error": "...", "status": "error"}
Performance
- Response Time: 1-7 seconds
- Timeout: 60 seconds
- Concurrency: Multiple simultaneous requests supported
Best Practices
- Start with
get_dataset_metadatato find schema IDs - Be specific in natural language queries
- Always check the
statusfield in responses - Cache frequent queries for better performance
Usage Examples
Here are three realistic examples showing how AI assistants can interact with the Lumenore Analytics MCP Server:
Example 1: Sales Performance Analysis
Scenario: A business analyst wants to understand sales performance for the last quarter.
AI Assistant Interaction:
# Step 1: Get available datasets
metadata = await client.call_tool("get_dataset_metadata", {})
# Step 2: Query sales data
sales_data = await client.call_tool("nlq_to_data", {
"userQuery": "Show me total sales by region for Q4 2024, sorted by highest sales",
"schemaId": 35403
})
# Step 3: Analyze trends
trend_analysis = await client.call_tool("get_trend_data", {
"userQuery": "What are the monthly sales trends for Q4 2024?",
"schemaId": 35403
})
# Step 4: Identify top performers
pareto_analysis = await client.call_tool("get_pareto_data", {
"userQuery": "Which products contribute to 80% of our sales?",
"schemaId": 35403
})
Expected Insights:
- Regional sales breakdown with totals
- Monthly trend visualization showing growth/decline
- Product contribution analysis highlighting key revenue drivers
Example 2: Customer Behavior Analysis
Scenario: A marketing team wants to understand customer purchasing patterns and detect anomalies.
AI Assistant Interaction:
# Step 1: Get customer dataset information
metadata = await client.call_tool("get_dataset_metadata", {})
# Step 2: Analyze customer segments
customer_data = await client.call_tool("nlq_to_data", {
"userQuery": "Show customer demographics and average order value by age group",
"schemaId": 35404
})
# Step 3: Detect unusual patterns
anomaly_detection = await client.call_tool("get_outlier_data", {
"userQuery": "Find customers with unusually high order values or frequency",
"schemaId": 35404
})
# Step 4: Understand correlations
correlation_analysis = await client.call_tool("get_correlation_data", {
"userQuery": "What factors correlate with customer lifetime value?",
"schemaId": 35404
})
Expected Insights:
- Customer segmentation by demographics and spending
- Identification of potential fraud or VIP customers
- Key drivers of customer value for targeted marketing
Example 3: Inventory Optimization
Scenario: An operations manager needs to optimize inventory levels based on demand patterns and forecasts.
AI Assistant Interaction:
# Step 1: Get inventory dataset
metadata = await client.call_tool("get_dataset_metadata", {})
# Step 2: Analyze historical demand
demand_data = await client.call_tool("nlq_to_data", {
"userQuery": "Show monthly demand for each product category over the past year",
"schemaId": 35405
})
# Step 3: Identify trends
trend_analysis = await client.call_tool("get_trend_data", {
"userQuery": "What are the demand trends for each product category?",
"schemaId": 35405
})
# Step 4: Generate forecasts
forecast = await client.call_tool("get_prediction_data", {
"userQuery": "Predict demand for next 3 months by product category",
"schemaId": 35405
})
# Step 5: Detect demand changes
change_detection = await client.call_tool("get_change_data", {
"userQuery": "Have there been any significant changes in demand patterns recently?",
"schemaId": 35405
})
Expected Insights:
- Historical demand patterns by category
- Future demand forecasts with confidence intervals
- Early warning of demand pattern shifts
- Data-driven inventory optimization recommendations
Benefits:
- Automated data refresh without manual intervention
- Real-time insights for operational decision-making
- Reduced load on backend systems through efficient caching
Best Practices from Examples
- Start with Metadata: Always use
get_dataset_metadatato understand available datasets - Combine Tools: Use multiple tools together for comprehensive analysis
- Specific Queries: Be clear and specific in natural language queries
- Error Handling: Always check response status before processing results
- Performance: Cache frequently accessed data to improve response times
Claude Prompts
Here are example prompts you can use with Claude when connected to this MCP server:
For Sales Analysis:
"Use the Lumenore Analytics tools to analyze our Q4 sales performance. I need to see regional breakdowns, identify top-performing products, and understand sales trends."
For Customer Insights:
Analyze customer demographics, find any unusual purchasing patterns, and identify what factors drive customer value. Use the available analytics tools to provide comprehensive insights."
For Inventory Management:
"generate forecasts for next quarter, and identify any recent changes in demand behavior using the predictive and trend analysis tools."
Error Handling
All tools implement comprehensive error handling with specific error types:
# Validation errors
{
"error": "Invalid request parameters: <details>",
"status": "validation_error",
"query": "<user_query>",
"schema_id": <schema_id>
}
# Service errors
{
"error": "<Operation> failed: <details>",
"status": "error",
"query": "<user_query>",
"schema_id": <schema_id>
}
Testing the Server
You can test the MCP server using any MCP-compatible client or by making HTTP requests to the SSE endpoint:
# Example: Testing with curl (adjust based on MCP protocol)
curl -N http://localhost:8080
Security & Privacy
Security Overview
The Lumenore Analytics MCP Server implements multiple layers of security to protect your data and API credentials:
Data Protection
- In-Memory Processing: All data is processed in-memory and immediately discarded after response generation
- No Data Storage: The MCP server does not store or log any user queries, schema IDs, or response data
- Secure Communication: All backend API requests use HTTPS encryption
- Credentials Security: Client credentials are never logged, stored, or exposed in responses
Authentication Security
- Client Credentials Flow: Industry-standard authentication using client ID and secret
- Session Management: Secure cookie-based session handling with automatic token refresh
- No MCP-Level Auth: MCP connection doesn't require authentication (backend auth is handled server-side)
- Security Monitoring: Failed authentication attempts are logged for security analysis
Credentials Best Practices
- Environment Variables: Store credentials in environment variables or
.envfiles (never in code) - Regular Rotation: Rotate credentials every 90 days or as needed
- Scope Limitation: Use credentials with minimal required permissions
- Separate Environments: Use different credentials for development, staging, and production
Privacy Policy
For detailed information about how Lumenore handles your data, please see our Privacy Policy.
Key Privacy Principles
- Minimal Data Processing: Only processes queries and schema IDs provided by users
- No Conversation History: Does not store or log conversation history
- User Control: Users control what data is queried and analyzed
- Compliance: Designed to comply with data protection regulations (GDPR, CCPA)
Data Flow Privacy
User Query → MCP Server → Lumenore Backend → Results → User
(No storage) (Lumenore's privacy policy applies)
Privacy Considerations
- The MCP server acts as a secure proxy between AI assistants and Lumenore's backend
- All privacy and data handling policies of Lumenore's backend API apply to your data
- The server itself does not retain any user data beyond the immediate request processing
- Users are responsible for ensuring their queries comply with applicable data protection laws
Compliance
Regulatory Compliance
- GDPR: Compliant with General Data Protection Regulation
- CCPA: Compliant with California Consumer Privacy Act
- SOC 2: Backend services follow SOC 2 security standards
- ISO 27001: Information security management best practices
Data Residency
- Data processing occurs in Lumenore's cloud infrastructure
- Data residency requirements should be discussed with Lumenore sales team
- Enterprise deployments may support private cloud or on-premise options
Security Configuration
Environment Security
# Secure credentials management
export LUMENORE_CLIENT_ID="your_client_id"
export LUMENORE_SECRET="your_secret"
# Restrict file permissions
chmod 600 .env
chmod 700 /path/to/server/directory
# Use secure network connections only
# Avoid using public Wi-Fi for sensitive operations
Production Security
- Use dedicated client credentials for production environments
- Implement credential rotation automation
- Monitor API usage and set up alerts for unusual activity
- Consider implementing IP allowlisting for API access
- Use VPN or private networks for server communication
Vulnerability Management
Reporting Security Issues
We take security seriously. If you find a vulnerability:
- Email: askme@lumenore.com
- Include vulnerability details and reproduction steps
- We will acknowledge within 24 hours
- Work with us to resolve the issue before public disclosure
Security Updates
- Security patches are prioritized and deployed quickly
- Subscribe to security notifications via our support channels
- Regular security assessments are performed on the infrastructure
Data Encryption
In Transit
- All API communications use TLS 1.2+ encryption
- HTTPS is enforced for all backend connections
- Certificate pinning can be implemented for enhanced security
At Rest
- Backend data storage uses encryption at rest
- Database encryption protects stored analytics data
- Key management follows industry best practices
Access Control
Principle of Least Privilege
- Client credentials should have minimal required permissions
- Separate credentials for different applications and environments
- Regular review of credential permissions and usage
Network Security
- Firewall rules restrict access to necessary ports only
- Consider implementing VPN access for server management
- Use network segmentation for production deployments
Troubleshooting
Quick Diagnostic Steps
- Check server is running:
curl -I http://localhost:8080 - Verify token is loaded: Check server startup logs for "No authorization token" warning
- Test backend connectivity:
curl -I https://preview.lumenore.com - Check MCP protocol: Ensure client is using Streamable HTTP transport
Example client configuration:
{
"server": {
"lumenore-server": {
"type": "streamable-http",
"url": "http://localhost:8080/mcp",
}
}
}
Manual testing with Python:
from config import config
from core.lumenore_analytics import LumenoreAnalytics
import asyncio
async def test():
client = LumenoreAnalytics()
result = await client.make_request('get-domain', method='GET')
print(result)
asyncio.run(test())
Getting Help
If you've tried the above steps and still have issues:
- Check server logs for detailed error messages
- Verify token validity and permissions
- Test backend API directly to isolate MCP vs backend issues
- Review MCP client configuration for transport and URL settings
- Contact support with logs and error messages (see Support section)
Contributing
We welcome contributions to the Lumenore Analytics MCP Server! Please follow these guidelines:
Code of Conduct
Please note that this project is released with a Contributor Covenant. By participating, you are expected to uphold this code.
How to Contribute
- Fork the repository
- Create a 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
Development Setup
# Clone your fork
git clone <your-fork-url>
cd lumenore-mcp
# Install development dependencies
pip install -r requirements.txt
# Run tests (if available)
python -m pytest
Reporting Bugs
Use the issue tracker to report bugs. Include:
- Steps to reproduce
- Expected vs actual behavior
- Environment details (Python version, OS)
Feature Requests
We welcome feature requests through GitHub Issues. Please:
- Search existing issues first
- Provide clear use cases
- Explain the desired functionality
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
Contact Information
For technical support and inquiries:
- Email: askme@lumenore.com
- Website: https://lumenore.com/
- Documentation: Lumenore Analytics Docs
Version: 1.0.0
Last Updated: January 2026
Python: 3.13+
MCP Protocol: Compatible with MCP 2024-11-05 specification