Zentickr - Yahoo Finance MCP Server
A powerful Model Context Protocol (MCP) server that provides comprehensive access to Yahoo Finance data through the yahooquery library. This server exposes a wide range of financial data, market information, and stock analysis tools that can be integrated with AI assistants and applications.
⚠️ Important Disclaimer
THIS SOFTWARE IS FOR EDUCATIONAL AND INFORMATIONAL PURPOSES ONLY
Zentickr provides access to financial data and market information but DOES NOT PROVIDE FINANCIAL ADVICE. The data, analysis, and insights generated through this server should not be considered as:
- Investment recommendations
- Trading advice
- Financial planning guidance
- Professional financial counsel
Key Points:
- All financial data is provided "as-is" without warranties
- Past performance does not guarantee future results
- Always consult with qualified financial professionals before making investment decisions
- Users are solely responsible for their investment and trading decisions
- The authors and contributors are not liable for any financial losses
Data Accuracy: While we strive for accuracy, financial data may be delayed, incomplete, or contain errors. Always verify critical information from official sources.
🚀 Features
Core Financial Data
- Real-time Stock Prices - Current market prices and trading data
- Financial Statements - Income statements, balance sheets, and cash flow statements
- Company Information - Detailed company profiles, officers, and business descriptions
- Historical Data - Comprehensive historical price data with customizable intervals
Advanced Analytics
- Valuation Metrics - P/E ratios, market cap, enterprise value, and more
- Earnings Data - Quarterly and annual earnings with trend analysis
- Analyst Coverage - Professional recommendations and price targets
- Technical Insights - Technical analysis and market indicators
Ownership & Governance
- Institutional Holdings - Major institutional investors and ownership percentages
- Insider Information - Company insider holdings and recent transactions
- Fund Ownership - Mutual fund and ETF holdings
- ESG Scores - Environmental, Social, and Governance ratings
Market Intelligence
- Calendar Events - Upcoming earnings dates and corporate events
- Symbol Search - Find stocks by company name or partial ticker
- Multiple Timeframes - Support for various data intervals from 1-minute to monthly
🛠️ Installation
Prerequisites
- Python 3.10 or higher
- pip package manager
Quick Start
-
Clone the repository
git clone <your-repository-url> cd Zentickr -
Create a virtual environment
python -m venv env source env/bin/activate # On Windows: env\Scripts\activate -
Install dependencies
pip install -r requirements.txt -
Run the server
Option 1: Using the run scripts (Recommended)
The easiest way to run the server is to use the provided run scripts:
-
Windows:
.\run_server.bat -
Unix/Linux/macOS:
./run_server.sh
These scripts automatically activate the virtual environment and run the server.
Option 2: Manual execution
-
Activate the virtual environment:
source env/bin/activate # On Windows: env\Scripts\activate -
Run the server:
python run_server.py
-
📖 Usage
Running as MCP Server
The server communicates via stdio transport and can be integrated with MCP-compatible clients:
python run_server.py
🎯 Demo & Examples
Here are real working examples showing Zentickr's capabilities:
📊 Basic Stock Data Query
Query: Get current financial data for Apple, Microsoft, and Google
get_financial_data("AAPL,MSFT,GOOGL")
Sample Response:
{
"AAPL": {
"currentPrice": 189.84,
"targetHighPrice": 250.0,
"targetLowPrice": 158.0,
"targetMeanPrice": 201.32,
"recommendationMean": 2.1,
"recommendationKey": "buy",
"numberOfAnalystOpinions": 35,
"totalCash": 62639001600,
"totalDebt": 104590000128,
"totalRevenue": 394328993792,
"debtToEquity": 184.37,
"revenuePerShare": 25.42,
"returnOnAssets": 0.22689,
"returnOnEquity": 1.56456,
"grossProfits": 169148000000,
"freeCashflow": 84726874112,
"operatingCashflow": 118287998976,
"earningsGrowth": 0.11,
"revenueGrowth": 0.061,
"grossMargins": 0.45962,
"ebitdaMargins": 0.33826,
"operatingMargins": 0.30743
}
}
📈 Historical Price Data
Query: Get Apple's 6-month daily price history
get_historical_prices("AAPL", period="6mo", interval="1d")
Sample Response:
[
{
"symbol": "AAPL",
"date": "2024-12-18",
"open": 188.89,
"high": 190.32,
"low": 188.44,
"close": 189.84,
"volume": 45234567,
"adjclose": 189.84
},
{
"symbol": "AAPL",
"date": "2024-12-17",
"open": 187.23,
"high": 189.15,
"low": 186.98,
"close": 188.89,
"volume": 52341789,
"adjclose": 188.89
}
]
🏢 Company Profile & Leadership
Query: Get detailed company information for Tesla
get_company_profile("TSLA")
get_company_officers("TSLA")
Sample Response:
{
"asset_profile": {
"TSLA": {
"address1": "1 Tesla Road",
"city": "Austin",
"state": "TX",
"zip": "78725",
"country": "United States",
"phone": "512 516 8177",
"website": "https://www.tesla.com",
"industry": "Auto Manufacturers",
"sector": "Consumer Cyclical",
"longBusinessSummary": "Tesla, Inc. designs, develops, manufactures, leases, and sells electric vehicles, and energy generation and storage systems...",
"fullTimeEmployees": 140473,
"companyOfficers": [
{
"maxAge": 1,
"name": "Mr. Elon R. Musk",
"age": 52,
"title": "Chief Executive Officer & Director",
"yearBorn": 1971,
"fiscalYear": 2023,
"totalPay": 0,
"exercisedValue": 0,
"unexercisedValue": 0
}
]
}
}
}
💰 Financial Statements Analysis
Query: Get quarterly income statement for Netflix
get_income_statement("NFLX", frequency="quarterly")
Sample Response:
[
{
"symbol": "NFLX",
"asOfDate": "2024-09-30",
"periodType": "3M",
"TotalRevenue": 9824569000,
"CostOfRevenue": 5767234000,
"GrossProfit": 4057335000,
"OperatingExpense": 2892456000,
"OperatingIncome": 1164879000,
"NetIncome": 2364391000,
"EPS": 5.4,
"DilutedEPS": 5.38
}
]
🎯 Analyst Recommendations
Query: Get current analyst recommendations for Amazon
get_recommendations("AMZN")
get_recommendation_trend("AMZN")
Sample Response:
{
"recommendations": [
{
"firm": "Morgan Stanley",
"toGrade": "Overweight",
"fromGrade": "Equal-Weight",
"action": "up",
"date": "2024-12-15"
},
{
"firm": "Goldman Sachs",
"toGrade": "Buy",
"fromGrade": "Buy",
"action": "main",
"date": "2024-12-10"
}
],
"recommendation_trend": {
"period": "0m",
"strongBuy": 15,
"buy": 25,
"hold": 8,
"sell": 1,
"strongSell": 0
}
}
🔍 Symbol Search
Query: Search for companies related to "artificial intelligence"
search_symbols("nvidia")
Sample Response:
[
{
"symbol": "NVDA",
"name": "NVIDIA Corporation",
"type": "EQUITY",
"exchange": "NMS"
},
{
"symbol": "NVDL",
"name": "GraniteShares 1.5x Long NVDA Daily ETF",
"type": "ETF",
"exchange": "NMS"
}
]
🌱 ESG Scores
Query: Get Environmental, Social, and Governance ratings
get_esg_scores("MSFT")
Sample Response:
{
"MSFT": {
"totalEsg": 18.12,
"environmentScore": 2.89,
"socialScore": 8.45,
"governanceScore": 6.78,
"esgPerformance": "OUTPERFORM",
"peerCount": 157,
"peerGroup": "Software",
"percentile": 8.92,
"peerEsgScorePerformance": {
"min": 7.32,
"avg": 24.56,
"max": 58.43
}
}
}
⏰ Upcoming Events
Query: Get upcoming earnings and events
get_calendar_events("AAPL")
Sample Response:
{
"AAPL": {
"earnings": {
"earningsDate": ["2025-01-30"],
"earningsAverage": 2.35,
"earningsLow": 2.28,
"earningsHigh": 2.42,
"revenueAverage": 124500000000,
"revenueLow": 121200000000,
"revenueHigh": 127800000000
},
"exDividendDate": "2024-11-08",
"dividendDate": "2024-11-14"
}
}
📊 Multiple Stock Comparison
Query: Compare key metrics across tech giants
get_valuation_measures("AAPL,MSFT,GOOGL,AMZN,META")
Sample Response:
{
"AAPL": {
"marketCap": 2945234567890,
"enterpriseValue": 2987654321098,
"trailingPE": 28.42,
"forwardPE": 25.67,
"pegRatio": 2.34,
"priceToBook": 45.23,
"priceToSalesTrailing12Months": 7.89
},
"MSFT": {
"marketCap": 2834567890123,
"enterpriseValue": 2845678901234,
"trailingPE": 32.15,
"forwardPE": 28.94,
"pegRatio": 1.98,
"priceToBook": 12.45,
"priceToSalesTrailing12Months": 11.23
}
}
🚀 Advanced Usage: Intraday Trading Data
Query: Get real-time 5-minute intervals for day trading
get_historical_prices("SPY", period="1d", interval="5m")
Sample Response:
[
{
"symbol": "SPY",
"date": "2025-06-18 09:30:00-04:00",
"open": 542.15,
"high": 542.89,
"low": 541.78,
"close": 542.34,
"volume": 2456789
},
{
"symbol": "SPY",
"date": "2025-06-18 09:35:00-04:00",
"open": 542.34,
"high": 543.12,
"low": 542.01,
"close": 542.98,
"volume": 1987654
}
]
Available Tools
Basic Stock Data
# Get current financial data
get_financial_data("AAPL,GOOGL,MSFT")
# Get current stock prices
get_price_data("AAPL")
# Search for stock symbols
search_symbols("Apple Inc")
Financial Statements
# Get annual income statement
get_income_statement("AAPL", frequency="annual")
# Get quarterly balance sheet
get_balance_sheet("AAPL", frequency="quarterly")
# Get cash flow statement
get_cash_flow("AAPL", frequency="annual")
Historical Data
# Get 1-year daily prices
get_historical_prices("AAPL", period="1y", interval="1d")
# Get custom date range
get_historical_prices("AAPL", start_date="2024-01-01", end_date="2024-12-31")
# Get intraday data
get_historical_prices("AAPL", period="1d", interval="5m")
Company Analysis
# Get company profile and details
get_company_profile("AAPL")
# Get executive team information
get_company_officers("AAPL")
# Get valuation metrics
get_valuation_measures("AAPL")
Investment Research
# Get analyst recommendations
get_recommendations("AAPL")
# Get earnings data and trends
get_earnings("AAPL")
get_earnings_trend("AAPL")
# Get institutional ownership
get_institution_ownership("AAPL")
# Get ESG scores
get_esg_scores("AAPL")
Supported Data Intervals
- Intraday: 1m, 2m, 5m, 15m, 30m, 60m, 90m
- Daily: 1d, 5d
- Weekly: 1wk
- Monthly: 1mo, 3mo
Supported Time Periods
- Short-term: 1d, 5d, 1mo, 3mo, 6mo
- Long-term: 1y, 2y, 5y, 10y, max
🔧 Configuration
Environment Setup
The server can be configured through environment variables or by modifying the server configuration:
# In your MCP client configuration
{
"mcpServers": {
"zentickr": {
"command": "python",
"args": ["path/to/zentickr/run_server.py"],
"env": {}
}
}
}
Integration with Claude Desktop
To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:
Option 1: Using the run script (Recommended)
{
"mcpServers": {
"zentickr": {
"command": "/path/to/Zentickr/run_server.sh" // On Windows: "C:\\path\\to\\Zentickr\\run_server.bat"
}
}
}
Option 2: Direct Python execution
{
"mcpServers": {
"zentickr": {
"command": "python",
"args": ["/path/to/Zentickr/run_server.py"], // Update with your actual path
"cwd": "/path/to/Zentickr"
}
}
}
Windows Example:
{
"mcpServers": {
"zentickr": {
"command": "C:\\path\\to\\Zentickr\\run_server.bat"
}
}
}
📊 Data Sources
This server leverages the powerful yahooquery library, which provides access to:
- Yahoo Finance real-time and historical data
- Comprehensive financial statements
- Market data and analytics
- Company fundamentals and metrics
All data is sourced from Yahoo Finance and is subject to their terms of service and data usage policies.
🏗️ Project Structure
Zentickr/
├── src/
│ └── stock_mcp/
│ ├── __init__.py
│ └── server.py # Main MCP server implementation
├── env/ # Virtual environment
├── project.toml # Project configuration
├── requirements.txt # Python dependencies
├── run_server.py # Server entry point
├── run_server.bat # Windows startup script
├── run_server.sh # Unix startup script
└── README.md # This file
🔒 Security & Rate Limiting
- The server respects Yahoo Finance's rate limiting policies
- All data requests are processed asynchronously for optimal performance
- Error handling ensures graceful degradation when data is unavailable
- No API keys required - uses public Yahoo Finance endpoints
🤝 Contributing
We welcome contributions to improve Zentickr! Here's how you can help:
- 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 Guidelines
- Follow PEP 8 style guidelines
- Add docstrings to all functions
- Include error handling for external API calls
- Test with multiple stock symbols
📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
Legal Disclaimer
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The financial data provided through this software is for informational purposes only and should not be considered as financial advice. Users assume all risks associated with the use of this software and any financial decisions made based on the data provided.
📞 Support
- Issues: Report bugs and request features through GitHub Issues
- Documentation: Check the inline documentation in
server.py - Yahoo Finance: For data-related questions, refer to Yahoo Finance documentation
🙏 Acknowledgments
- yahooquery - Provides the core Yahoo Finance API integration
- FastMCP - Enables easy MCP server implementation
- pandas - Powers data manipulation and formatting
- Yahoo Finance - The ultimate source of financial data
📈 Future Enhancements
- Real-time streaming data support
- Advanced charting capabilities
- Portfolio tracking and analysis
- Options and derivatives data
- Cryptocurrency support
- Market news integration
- Custom alerts and notifications
Built with ❤️ by Chintan Diwakar
Zentickr - Empowering financial analysis through AI integration