Stonks

An intelligent MCP (Model Context Protocol) server that automates stock analysis and news updates in Google Sheets using AI-powered insights.

🚀 Features

Core Capabilities

• Google Sheets Integration: Seamlessly connects to your Google Sheets for real-time stock data management
• AI-Powered Analysis: Uses Google Gemini to generate comprehensive stock analysis
• Multi-Type Analysis: Supports 5 different analysis types for comprehensive coverage
• Institutional Data Visualization: Creates charts for institutional ownership data
• Automated News Updates: Fetches and summarizes latest stock news

Analysis Types Available

1. 📰 News Analysis + Market Context (Column D)

   • Company-specific news and earnings
   • Broader market trends and economic factors
   • Geopolitical impact and industry disruption

2. 🤖 AI-Powered Insights (Column E)

   • Predictive modeling and pattern recognition
   • Scenario analysis with probability assessments
   • Market timing indicators

3. 📊 Investor Insights (Column F)

   • Technical and fundamental analysis
   • Risk assessment and competitive analysis
   • Sector dynamics and catalyst calendar

4. 💰 Quick Financials Overview (Column G)

   • Key financial metrics and ratios
   • Growth rates and profitability analysis
   • Liquidity and valuation metrics

5. 🏢 Institutional Information (Column H)

   • Institutional ownership data
   • Hedge fund and mutual fund activity
   • Insider trading and analyst coverage

🛠️ Setup Instructions

Prerequisites

• Python 3.8+
• Google Cloud Console account
• Google Sheets API access

1. Google Sheets API Setup

Follow the official Google guide to set up API access: Google Sheets API Quickstart

2. Installation

# Clone the repository
git clone <your-repo-url>
cd stocks

# Create virtual environment
python -m venv stocks
source stocks/bin/activate  # On Windows: stocks\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configuration

1. Download credentials.json from Google Cloud Console
2. Place it in the project root directory
3. Create .env file with:

GOOGLE_API_KEY=your_gemini_api_key
SPREADSHEET_ID=your_google_sheets_id
RANGE_NAME=Sheet1!A6:C9

4. Usage

Option A: Standalone Mode

# Start the MCP Server
python server.py

# Run the Client
python client.py server.py

Option B: MCP Client Integration

Add to your MCP client configuration:

{
  "mcpServers": {
    "stonks-server": {
      "command": "path to your python bin",
      "args": ["path to server.py"]
    }
  }
}

Note: Update the paths to match your actual installation directory.

🎯 How It Works

1. Initialize: Authenticate with Google Sheets API
2. Get Stocks: Retrieve stock data from your spreadsheet
3. Analyze: Generate AI-powered analysis for each stock
4. Update: Automatically populate analysis in designated columns
5. Visualize: Create institutional ownership charts

📋 Available MCP Tools

• initialize(): Set up Google Sheets authentication
• get_stocks(): Fetch stock data from spreadsheet
• update(): Add analysis to specific cells with multiple analysis types
• search_news(): Generate news summaries using Gemini AI
• plot_institutional_chart(): Create ownership visualization charts

These tools are available through any MCP-compatible client (Claude Desktop, etc.)

🔧 Technical Architecture

• MCP Server: FastMCP framework for tool orchestration
• AI Integration: Google Gemini for intelligent analysis
• Data Visualization: Matplotlib for institutional charts
• Authentication: OAuth2 for secure Google Sheets access
• Client Interface: LangGraph with React agent for natural language interaction

📊 Sample Workflow

User: "Update all stocks with latest news and analysis"
↓
Agent: 
1. Initializes Google Sheets connection
2. Retrieves stock symbols from spreadsheet
3. Generates news analysis for each stock
4. Updates respective columns with AI insights
5. Creates institutional ownership charts

🚨 Important Notes

• Analysis is based on last 10 days of data
• Includes references to SeekingAlpha, TradingTerminal, and TradingView
• Not financial advice - for informational purposes only
• Requires valid Google API credentials

📈 Future Enhancements

• Real-time data integration
• Advanced charting capabilities
• Portfolio performance tracking
• Custom analysis templates
• Multi-exchange support

---

Setup Guide: Google Sheets API Quickstart