Analytical MCP Server
Model Context Protocol server providing statistical analysis, decision support, logical reasoning, and research verification tools for Claude.
Setup
Prerequisites
- Node.js >= 20.0.0
- EXA_API_KEY environment variable (for research features)
Installation
Option 1: Direct Installation
npm install
npm run build
Option 2: Docker
# Build the Docker image
docker build -t analytical-mcp .
# Run with environment variables
docker run -d \
--name analytical-mcp \
-e EXA_API_KEY=your_api_key_here \
-v $(pwd)/cache:/app/cache \
analytical-mcp
# Or use docker-compose
cp .env.example .env
# Edit .env with your API key
docker-compose up -d
Configuration
Direct Installation Configuration
- Copy
.env.exampleto.env - Add your EXA_API_KEY to
.env - Add to Claude Desktop configuration:
{
"mcpServers": {
"analytical": {
"command": "node",
"args": ["/path/to/analytical-mcp/build/index.js"],
"env": {
"EXA_API_KEY": "your-exa-api-key-here"
}
}
}
}
Docker Configuration
- Copy
.env.exampleto.env - Add your EXA_API_KEY to
.env - Add to Claude Desktop configuration:
{
"mcpServers": {
"analytical": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", ".env",
"-v", "$(pwd)/cache:/app/cache",
"analytical-mcp"
]
}
}
}
Available Tools
Statistical Analysis
analytical:analyze_dataset- Statistical analysis of datasetsanalytical:advanced_regression_analysis- Linear, polynomial, and logistic regressionanalytical:hypothesis_testing- Statistical hypothesis testing (t-tests, chi-square, ANOVA)analytical:data_visualization_generator- Generate data visualization specifications
Decision Analysis
analytical:decision_analysis- Multi-criteria decision analysis with weighted scoring
Logical Reasoning
analytical:logical_argument_analyzer- Analyze argument structure and validityanalytical:logical_fallacy_detector- Detect logical fallacies in textanalytical:perspective_shifter- Generate alternative perspectives on problems
Research Verification
analytical:verify_research- Cross-verify research claims from multiple sources
Observability & Metrics
The Analytical MCP Server includes built-in observability features for monitoring circuit breakers and cache performance.
Metrics Endpoint
When enabled, the server exposes metrics via HTTP on port 9090 (configurable):
http://localhost:9090/metrics- Prometheus-style metricshttp://localhost:9090/metrics?format=json- JSON format metricshttp://localhost:9090/health- Health check endpointhttp://localhost:9090/- Metrics server status page
Available Metrics
Circuit Breaker Metrics
analytical_mcp_circuit_breaker_state- Current state (0=CLOSED, 1=HALF_OPEN, 2=OPEN)analytical_mcp_circuit_breaker_total_calls_total- Total calls through circuit breakeranalytical_mcp_circuit_breaker_rejected_calls_total- Rejected calls by circuit breakeranalytical_mcp_circuit_breaker_failure_count- Current failure countanalytical_mcp_circuit_breaker_success_count- Current success count
Cache Metrics
analytical_mcp_cache_hits_total- Cache hits by namespaceanalytical_mcp_cache_misses_total- Cache misses by namespaceanalytical_mcp_cache_puts_total- Cache puts by namespaceanalytical_mcp_cache_evictions_total- Cache evictions by namespaceanalytical_mcp_cache_size- Current cache size by namespace
System Metrics
analytical_mcp_uptime_seconds- Server uptime in secondsanalytical_mcp_memory_usage_bytes- Memory usage (RSS, heap, external)analytical_mcp_cpu_usage_microseconds- CPU time usage (user, system)
Configuration
Enable metrics by setting environment variables:
METRICS_ENABLED=true # Enable metrics server (default: true)
METRICS_PORT=9090 # Metrics server port (default: 9090)
METRICS_HOST=127.0.0.1 # Metrics server host (default: 127.0.0.1, use 0.0.0.0 to bind to all interfaces)
Usage Examples
# Get Prometheus metrics
curl http://localhost:9090/metrics
# Get JSON metrics
curl http://localhost:9090/metrics?format=json
# Health check
curl http://localhost:9090/health
Usage Examples
Dataset Analysis
{
"data": [23, 45, 67, 12, 89, 34, 56, 78],
"analysisType": "stats"
}
Decision Analysis
{
"options": ["Option A", "Option B", "Option C"],
"criteria": ["Cost", "Quality", "Speed"],
"weights": [0.4, 0.4, 0.2]
}
Logical Analysis
{
"argument": "All birds can fly. Penguins are birds. Therefore, penguins can fly.",
"analysisDepth": "comprehensive"
}
Development
Testing
# Run all tests
./tools/test-runner.sh
# Run specific test suite
./tools/test-runner.sh integration
# Available test suites: api-keys, server, integration, research, data-pipeline
Scripts
npm run build- Build TypeScript to JavaScriptnpm run watch- Watch for changes and rebuildnpm run test- Run Jest testsnpm run inspector- Start MCP inspector for debugging
Project Structure
analytical-mcp/
├── src/
│ ├── tools/ # MCP tool implementations
│ ├── utils/ # Utility functions
│ └── index.ts # Main server entry point
├── docs/ # Documentation
├── tools/ # Development and testing scripts
└── examples/ # Usage examples
Tool Categories
Statistical Analysis
- Descriptive statistics: mean, median, standard deviation, quartiles
- Correlation analysis
- Regression analysis: linear, polynomial, logistic
- Hypothesis testing: t-tests, chi-square, ANOVA
Decision Support
- Multi-criteria decision analysis
- Weighted scoring
- Trade-off analysis
- Risk assessment
Logical Reasoning
- Argument structure analysis
- Fallacy detection
- Perspective generation
- Critical analysis
Research Integration
- Multi-source verification
- Fact extraction
- Consistency checking
- Confidence scoring
Security and Privacy
- All processing occurs locally
- Research features use Exa API (optional, requires API key)
- No permanent data storage
- Optional file-based caching stored locally only
- API keys managed via environment variables
License
MIT License. See LICENSE file for details.
Contributing
- Fork the repository
- Create feature branch:
git checkout -b feature/your-feature - Make changes and commit:
git commit -m 'Add feature description' - Push to branch:
git push origin feature/your-feature - Open pull request
See docs/DEVELOPMENT.md for detailed development guidelines, code standards, and testing requirements.
Troubleshooting
Common Issues
JSON parsing errors: All logging must go to stderr, not stdout. MCP protocol uses stdout for communication. Use the Logger class, not console.log.
Tools not appearing: Verify server configuration in Claude Desktop settings and restart Claude Desktop application.
Research features disabled: Set EXA_API_KEY in your environment or .env file.
Server not starting: Check Node.js version is 20 or higher and all dependencies are installed with npm install.
See docs/TROUBLESHOOTING.md for detailed troubleshooting guidance.
Debug Mode
Start the server with the MCP inspector:
npm run inspector