Provides optional integration for AI-powered financial analysis features using OpenAI's language models
Supports PostgreSQL as a backend database option for storing financial data and analysis results
Uses Redis for intelligent caching of stock data and analysis results to improve performance
Uses SQLite as the default database backend for storing financial data and S&P 500 stock information
MaverickMCP - Personal Stock Analysis MCP Server
MaverickMCP is a personal-use FastMCP 2.0 server that provides professional-grade financial data analysis, technical indicators, and portfolio optimization tools directly to your Claude Desktop interface. Built for individual traders and investors, it offers comprehensive stock analysis capabilities without any authentication or billing complexity.
The server comes pre-seeded with all 520 S&P 500 stocks and provides advanced screening recommendations across multiple strategies. It runs locally with HTTP/SSE/STDIO transport options for seamless integration with Claude Desktop and other MCP clients.
Why MaverickMCP?
MaverickMCP provides professional-grade financial analysis tools directly within your Claude Desktop interface. Perfect for individual traders and investors who want comprehensive stock analysis capabilities without the complexity of expensive platforms or commercial services.
Key Benefits:
No Setup Complexity: Simple
make dev
command gets you running (oruv sync
+make dev
)Modern Python Tooling: Built with
uv
for lightning-fast dependency managementClaude Desktop Integration: Native MCP support for seamless AI-powered analysis
Comprehensive Analysis: 29+ financial tools covering technical indicators, screening, and portfolio optimization
Smart Caching: Redis-powered performance with graceful fallbacks
Fast Development: Hot reload, smart error handling, and parallel processing
Open Source: MIT licensed, community-driven development
Educational Focus: Perfect for learning financial analysis and MCP development
Features
Pre-seeded Database: 520 S&P 500 stocks with comprehensive screening recommendations
Advanced Backtesting: VectorBT-powered engine with 15+ built-in strategies and ML algorithms
Fast Development: Comprehensive Makefile, smart error handling, hot reload, and parallel processing
Stock Data Access: Historical and real-time stock data with intelligent caching
Technical Analysis: 20+ indicators including SMA, EMA, RSI, MACD, Bollinger Bands, and more
Stock Screening: Multiple strategies (Maverick Bullish/Bearish, Trending Breakouts) with parallel processing
Portfolio Tools: Correlation analysis, returns calculation, and optimization
Market Data: Sector performance, market movers, and earnings information
Smart Caching: Redis-powered performance with automatic fallback to in-memory storage
Database Support: SQLAlchemy integration with PostgreSQL/SQLite (defaults to SQLite)
Multi-Transport Support: HTTP, SSE, and STDIO transports for all MCP clients
Quick Start
Prerequisites
Python 3.12+: Core runtime environment
uv: Modern Python package manager (recommended)
TA-Lib: Technical analysis library for advanced indicators
Redis (optional, for enhanced caching)
PostgreSQL or SQLite (optional, for data persistence)
Installing TA-Lib
TA-Lib is required for technical analysis calculations.
macOS and Linux (Homebrew):
Windows (Multiple Options):
Option 1: Conda/Anaconda (Recommended - Easiest)
Option 2: Pre-compiled Wheels
Download the appropriate wheel for your Python version from:
Choose the file matching your Python version (e.g.,
TA_Lib-0.4.28-cp312-cp312-win_amd64.whl
for Python 3.12 64-bit)
Install using pip:
Option 3: Alternative Pre-compiled Package
Option 4: Build from Source (Advanced) If other methods fail, you can build from source:
Install Microsoft C++ Build Tools
Download and extract ta-lib C library to
C:\ta-lib
Build using Visual Studio tools
Run
pip install ta-lib
Verification: Test your installation:
Installing uv (Recommended)
Installation
Option 1: Using uv (Recommended - Fastest)
Option 2: Using pip (Traditional)
Start the Server
Connect to Claude Desktop
Recommended: SSE Connection (Stable and Reliable)
This configuration provides stable tool registration and prevents tools from disappearing:
Important: Note the trailing slash in
/sse/
- this is REQUIRED to prevent redirect issues!
Config File Location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Why This Configuration Works Best:
Stable tool registration - tools don't disappear after initial connection
Reliable connection management through SSE transport
Proper session persistence for long-running analysis tasks
All 29+ financial tools available consistently
Alternative: Direct STDIO Connection (Development Only)
Important: Always restart Claude Desktop after making configuration changes. The SSE configuration via mcp-remote has been tested and confirmed to provide stable, persistent tool access without connection drops.
That's it! MaverickMCP tools will now be available in your Claude Desktop interface.
Claude Desktop (Most Popular) - Recommended Configuration
Config Location:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Cursor IDE - STDIO and SSE
Option 1: STDIO (via mcp-remote):
Option 2: Direct SSE:
Config Location: Cursor → Settings → MCP Servers
Claude Code CLI - All Transports
HTTP Transport (Recommended):
SSE Transport (Alternative):
STDIO Transport (Development):
Windsurf IDE - STDIO and SSE
Option 1: STDIO (via mcp-remote):
Option 2: Direct SSE:
Config Location: Windsurf → Settings → Advanced Settings → MCP Servers
Why mcp-remote is Needed
The mcp-remote
tool bridges the gap between STDIO-only clients (like Claude Desktop) and HTTP/SSE servers. Without it, these clients cannot connect to remote MCP servers:
Without mcp-remote: Client tries STDIO → Server expects HTTP → Connection fails
With mcp-remote: Client uses STDIO → mcp-remote converts to HTTP → Server receives HTTP → Success
Available Tools
MaverickMCP provides 35+ financial analysis tools organized into focused categories, including advanced AI-powered research agents:
Development Commands
Testing
Code Quality
Configuration
Configure MaverickMCP via .env
file or environment variables:
Essential Settings:
REDIS_HOST
,REDIS_PORT
- Redis cache (optional, defaults to localhost:6379)DATABASE_URL
- PostgreSQL connection orsqlite:///maverick_mcp.db
for SQLite (default)LOG_LEVEL
- Logging verbosity (INFO, DEBUG, ERROR)S&P 500 data automatically seeds on first startup
Required API Keys:
TIINGO_API_KEY
- Stock data provider (free tier available at tiingo.com)
Optional API Keys:
OPENROUTER_API_KEY
- Strongly Recommended for Research: Access to 400+ AI models with intelligent cost optimization (40-60% cost savings)EXA_API_KEY
- Recommended for Research: Web search capabilities for comprehensive researchOPENAI_API_KEY
- Direct OpenAI access (fallback)ANTHROPIC_API_KEY
- Direct Anthropic access (fallback)FRED_API_KEY
- Federal Reserve economic dataTAVILY_API_KEY
- Alternative web search provider
Performance:
CACHE_ENABLED=true
- Enable Redis cachingCACHE_TTL_SECONDS=3600
- Cache duration
Usage Examples
Backtesting Example
Once connected to Claude Desktop, you can use natural language to run backtests:
Technical Analysis Example
Portfolio Optimization Example
Tools
MaverickMCP provides 35+ financial analysis tools organized by category, including advanced AI-powered research agents:
Stock Data Tools
fetch_stock_data
- Get historical stock data with intelligent cachingfetch_stock_data_batch
- Fetch data for multiple tickers simultaneouslyget_news_sentiment
- Analyze news sentiment for any tickerclear_cache
/get_cache_info
- Cache management utilities
Technical Analysis Tools
get_rsi_analysis
- RSI calculation with buy/sell signalsget_macd_analysis
- MACD analysis with trend identificationget_support_resistance
- Identify key price levelsget_full_technical_analysis
- Comprehensive technical analysisget_stock_chart_analysis
- Visual chart generation
Portfolio Tools
risk_adjusted_analysis
- Risk-based position sizingcompare_tickers
- Side-by-side ticker comparisonportfolio_correlation_analysis
- Correlation matrix analysis
Stock Screening Tools (Pre-seeded with S&P 500)
get_maverick_stocks
- Bullish momentum screening from 520 S&P 500 stocksget_maverick_bear_stocks
- Bearish setup identification from pre-analyzed dataget_trending_breakout_stocks
- Strong uptrend phase screening with supply/demand analysisget_all_screening_recommendations
- Combined screening results across all strategiesDatabase includes comprehensive screening data updated regularly
Advanced Research Tools (NEW) - AI-Powered Deep Analysis
research_comprehensive
- Full parallel research with multiple AI agents (7-256x faster)research_company
- Company-specific deep research with financial analysisanalyze_market_sentiment
- Multi-source sentiment analysis with confidence trackingcoordinate_agents
- Multi-agent supervisor for complex research orchestration
Research Features:
Parallel Execution: 7-256x speedup with intelligent agent orchestration
Adaptive Timeouts: 120s-600s based on research depth and complexity
Smart Model Selection: Automatic selection from 400+ models via OpenRouter
Cost Optimization: 40-60% cost reduction through intelligent model routing
Early Termination: Confidence-based early stopping to save time and costs
Content Filtering: High-credibility source prioritization
Error Recovery: Circuit breakers and comprehensive error handling
Backtesting Tools (NEW) - Production-Ready Strategy Testing
run_backtest
- Execute backtests with VectorBT engine for any strategycompare_strategies
- A/B testing framework for strategy comparisonoptimize_strategy
- Walk-forward optimization with parameter tuninganalyze_backtest_results
- Comprehensive performance metrics and risk analysisget_backtest_report
- Generate detailed HTML reports with visualizations
Backtesting Features:
15+ Built-in Strategies: Including ML-powered adaptive, ensemble, and regime-aware algorithms
VectorBT Integration: High-performance vectorized backtesting engine
Parallel Processing: 7-256x speedup for multi-strategy evaluation
Advanced Metrics: Sharpe, Sortino, Calmar ratios, maximum drawdown, win rate
Walk-Forward Optimization: Out-of-sample testing and validation
Monte Carlo Simulations: Robustness testing with confidence intervals
Multi-Timeframe Support: From 1-minute to monthly data
Custom Strategy Development: Easy-to-use templates for custom strategies
Market Data Tools
Market overview, sector performance, earnings calendars
Economic indicators and Federal Reserve data
Real-time market movers and sentiment analysis
Resources
stock://{ticker}
- Latest year of stock datastock://{ticker}/{start_date}/{end_date}
- Custom date rangestock_info://{ticker}
- Basic stock information
Prompts
stock_analysis(ticker)
- Comprehensive stock analysis promptmarket_comparison(tickers)
- Compare multiple stocksportfolio_optimization(tickers, risk_profile)
- Portfolio optimization guidance
Test Examples - Validate All Features
Test the comprehensive research capabilities and parallel processing improvements with these examples:
Core Research Features
Basic Research with Timeout Protection
"Research the current state of the AI semiconductor industry and identify the top 3 investment opportunities"Tests: Basic research, adaptive timeouts, industry analysis
Comprehensive Company Research with Parallel Agents
"Provide comprehensive research on NVDA including fundamental analysis, technical indicators, competitive positioning, and market sentiment using multiple research approaches"Tests: Parallel orchestration, multi-agent coordination, company research
Cost-Optimized Quick Research
"Give me a quick overview of AAPL's recent earnings and stock performance"Tests: Intelligent model selection, cost optimization, quick analysis
Performance Testing
Parallel Performance Benchmark
"Research and compare MSFT, GOOGL, and AMZN simultaneously focusing on cloud computing revenue growth"Tests: Parallel execution speedup (7-256x), multi-company analysis
Deep Research with Early Termination
"Conduct exhaustive research on Tesla's autonomous driving technology and its impact on the stock valuation"Tests: Deep research depth, confidence tracking, early termination (0.85 threshold)
Error Handling & Recovery
Error Recovery and Circuit Breaker Test
"Research 10 penny stocks with unusual options activity and provide risk assessments for each"Tests: Circuit breaker activation, error handling, fallback mechanisms
Supervisor Agent Coordination
"Analyze the renewable energy sector using both technical and fundamental analysis approaches, then synthesize the findings into actionable investment recommendations"Tests: Supervisor routing, agent coordination, result synthesis
Advanced Features
Sentiment Analysis with Content Filtering
"Analyze market sentiment for Bitcoin and cryptocurrency stocks over the past week, filtering for high-credibility sources only"Tests: Sentiment analysis, content filtering, source credibility
Timeout Stress Test
"Research the entire S&P 500 technology sector companies and rank them by growth potential"Tests: Timeout management, large-scale analysis, performance under load
Multi-Modal Research Integration
"Research AMD using technical analysis, then find recent news about their AI chips, analyze competitor Intel's position, and provide a comprehensive investment thesis with risk assessment"Tests: All research modes, integration, synthesis, risk assessment
Bonus Edge Case Tests
Empty/Invalid Query Handling
"Research [intentionally leave blank or use symbol that doesn't exist like XYZABC]"Tests: Error messages, helpful fix suggestions
Token Budget Optimization
"Provide the most comprehensive possible analysis of the entire semiconductor industry including all major players, supply chain dynamics, geopolitical factors, and 5-year projections"Tests: Progressive token allocation, budget management, depth vs breadth
Expected Performance Metrics
When running these tests, you should observe:
Parallel Speedup: 7-256x faster for multi-entity queries
Response Times: Simple queries ~10s, complex research 30-120s
Cost Efficiency: 60-80% reduction vs premium-only models
Confidence Scores: Early termination when confidence > 0.85
Error Recovery: Graceful degradation without crashes
Model Selection: Automatic routing to optimal models per task
Docker (Optional)
For containerized deployment:
Note: The Dockerfile uses uv
for fast dependency installation and smaller image sizes.
Troubleshooting
Common Issues
Tools Disappearing in Claude Desktop:
Solution: Ensure SSE endpoint has trailing slash:
http://localhost:8003/sse/
The 307 redirect from
/sse
to/sse/
causes tool registration to failAlways use the exact configuration with trailing slash shown above
Research Tool Timeouts:
Research tools have adaptive timeouts (120s-600s)
Deep research may take 2-10 minutes depending on complexity
Monitor progress in server logs with
make tail-log
OpenRouter Not Working:
Ensure
OPENROUTER_API_KEY
is set in.env
Check API key validity at openrouter.ai
System falls back to direct providers if OpenRouter unavailable
Extending MaverickMCP
Add custom financial analysis tools with simple decorators:
Development Tools
Quick Development Workflow
Smart Error Handling
MaverickMCP includes helpful error diagnostics:
DataFrame column case sensitivity → Shows correct column name
Connection failures → Provides specific fix commands
Import errors → Shows exact install commands
Database issues → Suggests SQLite fallback
Fast Development Options
Hot Reload:
uv run python tools/hot_reload.py
- Auto-restart on changesFast Startup:
./tools/fast_dev.sh
- < 3 second startupQuick Testing:
uv run python tools/quick_test.py --test stock
- Test specific featuresExperiment Harness: Drop .py files in
tools/experiments/
for auto-execution
Performance Features
Parallel Screening: 4x faster stock analysis with ProcessPoolExecutor
Smart Caching:
@quick_cache
decorator for instant re-runsOptimized Tests: Unit tests complete in 5-10 seconds
Getting Help
For issues or questions:
Check Documentation: Start with this README and CLAUDE.md
Search Issues: Look through existing GitHub issues
Report Bugs: Create a new issue with details
Request Features: Suggest improvements via GitHub issues
Contribute: See our Contributing Guide for development setup
Recent Updates
Production-Ready Backtesting Framework (NEW)
VectorBT Integration: High-performance vectorized backtesting engine for institutional-grade performance
15+ Built-in Strategies: Including ML-powered adaptive, ensemble, and regime-aware algorithms
Parallel Processing: 7-256x speedup for multi-strategy evaluation and optimization
Advanced Analytics: Comprehensive metrics including Sharpe, Sortino, Calmar ratios, and drawdown analysis
Walk-Forward Optimization: Out-of-sample testing with automatic parameter tuning
Monte Carlo Simulations: Robustness testing with confidence intervals
LangGraph Workflow: Multi-agent orchestration for intelligent strategy selection and validation
Production Features: Database persistence, batch processing, and HTML reporting
Advanced Research Agents
Parallel Research Execution: Achieved 7-256x speedup (exceeded 2x target) with intelligent agent orchestration
Adaptive Timeout Protection: Dynamic timeouts (120s-600s) based on research depth and complexity
Intelligent Model Selection: OpenRouter integration with 400+ models, 40-60% cost reduction
Comprehensive Error Handling: Circuit breakers, retry logic, and graceful degradation
Early Termination: Confidence-based stopping to optimize time and costs
Content Filtering: High-credibility source prioritization for quality results
Multi-Agent Orchestration: Supervisor pattern for complex research coordination
Performance Improvements
Parallel Agent Execution: Increased concurrent agents from 4 to 6
Optimized Semaphores: BoundedSemaphore for better resource management
Reduced Rate Limiting: Delays decreased from 0.5s to 0.05s
Batch Processing: Improved throughput for multiple research tasks
Smart Caching: Redis-powered with in-memory fallback
Testing & Quality
84% Test Coverage: 93 tests with comprehensive coverage
Zero Linting Errors: Fixed 947 issues for clean codebase
Full Type Annotations: Complete type coverage for research components
Error Recovery Testing: Comprehensive failure scenario coverage
Personal Use Optimization
No Authentication Required: Removed all authentication/billing complexity for personal use
Pre-seeded S&P 500 Database: 520 stocks with comprehensive screening recommendations
Simplified Architecture: Clean, focused codebase for core stock analysis functionality
Multi-Transport Support: HTTP, SSE, and STDIO for all MCP clients
Development Experience Improvements
Comprehensive Makefile: One command (
make dev
) starts everything including database seedingSmart Error Handling: Automatic fix suggestions for common issues
Fast Development: < 3 second startup with
./tools/fast_dev.sh
Parallel Processing: 4x speedup for stock screening operations
Enhanced Tooling: Hot reload, experiment harness, quick testing
Technical Improvements
Modern Tooling: Migrated to uv and ty for faster dependency management and type checking
Market Data: Improved fallback logic and async support
Caching: Smart Redis caching with graceful in-memory fallback
Database: SQLite default with PostgreSQL option for enhanced performance
Acknowledgments
MaverickMCP builds on these excellent open-source projects:
FastMCP - MCP framework powering the server
yfinance - Market data access
TA-Lib - Technical analysis indicators
FastAPI - Modern web framework
The entire Python open-source community
License
MIT License - see LICENSE file for details. Free to use for personal and commercial purposes.
Support
If you find MaverickMCP useful:
Star the repository
Report bugs via GitHub issues
Suggest features
Improve documentation
Built for traders and investors. Happy Trading!
Read the full build guide: How to Build an MCP Stock Analysis Server
Disclaimer
This software is for educational and informational purposes only. It is NOT financial advice.
Investment Risk Warning: Past performance does not guarantee future results. All investments carry risk of loss, including total loss of capital. Technical analysis and screening results are not predictive of future performance. Market data may be delayed, inaccurate, or incomplete.
No Professional Advice: This tool provides data analysis, not investment recommendations. Always consult with a qualified financial advisor before making investment decisions. The developers are not licensed financial advisors or investment professionals. Nothing in this software constitutes professional financial, investment, legal, or tax advice.
Data and Accuracy: Market data provided by third-party sources (Tiingo, Yahoo Finance, FRED). Data may contain errors, delays, or omissions. Technical indicators are mathematical calculations based on historical data. No warranty is made regarding data accuracy or completeness.
Regulatory Compliance: US Users - This software is not registered with the SEC, CFTC, or other regulatory bodies. International Users - Check local financial software regulations before use. Users are responsible for compliance with all applicable laws and regulations. Some features may not be available in certain jurisdictions.
Limitation of Liability: Developers disclaim all liability for investment losses or damages. Use this software at your own risk. No guarantee is made regarding software availability or functionality.
By using MaverickMCP, you acknowledge these risks and agree to use the software for educational purposes only.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A personal stock analysis MCP server that provides professional-grade financial data analysis, technical indicators, and portfolio optimization tools directly to your Claude Desktop interface. Pre-seeded with all 520 S&P 500 stocks and comprehensive screening recommendations for individual traders and investors.
Related MCP Servers
- -securityFlicense-qualityThe MCP Trader Server conducts comprehensive technical analysis on stocks, offering insights into trends, momentum indicators, volatility metrics, and volume analysis to support stock trading decisions.Last updated -247
- AsecurityAlicenseAqualityAn MCP server that provides comprehensive financial insights and analysis by leveraging real-time market data, news, and advanced analytics for stocks, options, financial statements, and economic indicators.Last updated -1747PythonMIT License
- AsecurityFlicenseAqualityA specialized MCP server for Claude Desktop that allows executing terminal commands for malware analysis with support for common analysis tools like file, strings, hexdump, objdump, and xxd.Last updated -72
- AsecurityFlicenseAqualityAn MCP server that enables Claude Desktop to access and analyze financial data through Yahoo Finance integration.Last updated -1