Lumenore-MCP

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

- Python 3.13+
- Lumenore client credentials (client ID and secret)
- Access to Lumenore server instance

git clone https://github.com/Lumenore-Platform/lumenore-mcp.git cd lumenore-mcp pip install -r requirements.txt

Create a.envfile in the project root with your credentials. You can use.env.exampleas a template:

LUMENORE_CLIENT_ID="your_client_id_here" LUMENORE_SECRET="your_secret_here" SERVER_URL="https://preview.lumenore.com"

The server runs onhttp://0.0.0.0:8080with SSE transport for real-time streaming.
- Settings → MCP Servers
- Add Server with:

Name: Lumenore Analytics URL: http://localhost:8080/mcp Transport: Streamable HTTP

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 })

- Protocol: MCP 2024-11-05+
- Transport: Streamable HTTP (SSE)
- Port: 8080 (default)
- Auth: No MCP-level auth required

curl -I http://localhost:8080 # Should return HTTP/1.1 200 OK

- Contact Lumenore support to obtain client credentials
- Receive yourLUMENORE_CLIENT_IDandLUMENORE_SECRET
- Store securely in your.envfile

"Authorization token missing or invalid":

- Verify credentials are set in.envfile:

- For client credentials: Check bothLUMENORE_CLIENT_IDandLUMENORE_SECRETare set

The server provides 8 powerful tools for data analysis:

get_dataset_metadata- Lists available datasets and schema IDs

nlq_to_data- Converts questions to structured data

{ "userQuery": "Top 5 sales regions last month", "schemaId": 123 }

get_trend_data- Identifies temporal patterns and trendsget_prediction_data- Generates forecasts and predictionsget_outlier_data- Detects anomalies and unusual patternsget_correlation_data- Analyzes variable relationshipsget_change_data- Detects pattern shifts and transitionsget_pareto_data- Performs 80/20 impact analysis

All tools return standardized responses:

- Success:{"data": {...}, "status": "success"}
- Validation Error:{"error": "...", "status": "validation_error"}
- Service Error:{"error": "...", "status": "error"}

- Response Time: 1-7 seconds
- Timeout: 60 seconds
- Concurrency: Multiple simultaneous requests supported
- Start withget_dataset_metadatato find schema IDs
- Be specific in natural language queries
- Always check thestatusfield in responses
- Cache frequent queries for better performance

Here are three realistic examples showing how AI assistants can interact with the Lumenore Analytics MCP Server:

Scenario: A business analyst wants to understand sales performance for the last quarter.

# 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 })

- Regional sales breakdown with totals
- Monthly trend visualization showing growth/decline
- Product contribution analysis highlighting key revenue drivers

Scenario: A marketing team wants to understand customer purchasing patterns and detect anomalies.

# 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 })

- Customer segmentation by demographics and spending
- Identification of potential fraud or VIP customers
- Key drivers of customer value for targeted marketing

Scenario: An operations manager needs to optimize inventory levels based on demand patterns and forecasts.

# 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 })

- Historical demand patterns by category
- Future demand forecasts with confidence intervals
- Early warning of demand pattern shifts
- Data-driven inventory optimization recommendations

- Automated data refresh without manual intervention
- Real-time insights for operational decision-making
- Reduced load on backend systems through efficient caching
- Start with Metadata: Always useget_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

Here are example prompts you can use with Claude when connected to this MCP server:

"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."

Analyze customer demographics, find any unusual purchasing patterns, and identify what factors drive customer value. Use the available analytics tools to provide comprehensive insights."

"generate forecasts for next quarter, and identify any recent changes in demand behavior using the predictive and trend analysis tools."

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> }

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

The Lumenore Analytics MCP Server implements multiple layers of security to protect your data and API credentials:

- 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

- 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

- 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)

User Query → MCP Server → Lumenore Backend → Results → User (No storage) (Lumenore's privacy policy applies)

- 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

- 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 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

# 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

- 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

- All API communications use TLS 1.2+ encryption
- HTTPS is enforced for all backend connections
- Certificate pinning can be implemented for enhanced security

- Backend data storage uses encryption at rest
- Database encryption protects stored analytics data
- Key management follows industry best practices

- Client credentials should have minimal required permissions
- Separate credentials for different applications and environments
- Regular review of credential permissions and usage

- Firewall rules restrict access to necessary ports only
- Consider implementing VPN access for server management
- Use network segmentation for production deployments
- 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

{ "server": { "lumenore-server": { "type": "streamable-http", "url": "http://localhost:8080/mcp", } } }

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())

We welcome contributions to the Lumenore Analytics MCP Server! Please follow these guidelines:

# 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

- Steps to reproduce
- Expected vs actual behavior
- Environment details (Python version, OS)