📊 Stock Valuation MCP Server

<div align="center"> <strong>A comprehensive Model Context Protocol (MCP) server for professional stock valuation and financial analysis</strong> </div>

---

📖 Table of Contents

• About
• Features
• Supported Tools
• Quick Start
• Oracle Cloud Deployment
• n8n Integration
• Documentation
• Installation
• Configuration
• API Documentation
• Usage Examples
• Deployment
• Architecture
• Contributing
• License

---

📝 About

The Stock Valuation MCP Server provides professional-grade financial analysis tools for stock valuation and investment decision-making. It integrates seamlessly with Claude Desktop and provides real-time data from Thai stock markets through the SET Watch API.

Key Capabilities

• Valuation Models: PE Band Analysis, Dividend Discount Model (DDM), Discounted Cash Flow (DCF)
• Real-time Data: Live stock data from SET Watch API
• Financial Statements: Complete income statement, balance sheet, and cash flow analysis
• Historical Analysis: Track and analyze financial ratios over time
• Investment Recommendations: Data-driven buy/sell/hold suggestions
• Secure Configuration: Environment-based configuration for API keys and secrets

---

✨ Features

📈 Valuation Tools

• PE Band Analysis - Historical PE ratio analysis with fair value ranges
• Dividend Discount Model (DDM) - Gordon Growth Model for dividend-paying stocks
• Discounted Cash Flow (DCF) - Intrinsic value calculation using free cash flow projections

🔍 Real-Time Data Integration

• SET Watch API Integration - Fetch real-time Thai stock data
• Financial Statements - Complete financial statement analysis
• Historical Ratios - Track PE, PBV, ROE, ROA, ROIC trends over time
• Automatic Calculations - Compute key financial ratios automatically

📊 Analysis Features

• Trend Analysis - Identify valuation and profitability trends
• Comparative Analysis - Compare against historical averages
• Investment Scoring - Generate buy/sell/hold recommendations
• Risk Metrics - Altman Z-Score, Piotroski F-Score calculations

🛡️ Security & Configuration

• Environment Variables - Secure API key and configuration management
• Oracle Cloud Ready - Optimized for Oracle Cloud Free Tier deployment
• Docker Support - Containerized deployment with environment injection
• Type Safety - Full TypeScript implementation with comprehensive type definitions

---

🛠️ Supported Tools

Tool Category	Tool Name	Description
Valuation	calculate_pe_band	Calculate PE band valuation with historical data
Valuation	calculate_ddm	Dividend Discount Model analysis
Valuation	calculate_dcf	Discounted Cash Flow valuation
Data Fetching	fetch_stock_data	Fetch real-time stock data from SET Watch
Data Fetching	complete_valuation	Run all valuation models with fetched data
Financial Statements	fetch_income_statement	Fetch income statement data
Financial Statements	fetch_balance_sheet	Fetch balance sheet data
Financial Statements	fetch_cash_flow_statement	Fetch cash flow statement data
Financial Statements	fetch_all_financial_statements	Fetch all statements with ratio analysis
Historical Analysis	fetch_historical_ratios	Fetch historical PE, PBV, ROE, ROA, ROIC data
Historical Analysis	analyze_historical_ratios	Analyze trends with investment recommendations

---

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• Claude Desktop (for MCP integration)
• Docker (optional, for containerized deployment)

Installation

# Clone the repository
git clone <repository-url>
cd myMCPserver

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Build the project
npm run build

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "stock-valuation": {
      "command": "node",
      "args": ["C:/Programing/ByAI/myMCPserver/dist/index.js"]
    }
  }
}

Restart Claude Desktop to start using the tools!

Quick Test with MCP Inspector

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector node dist/index.js

---

☁️ Oracle Cloud Deployment

One-Click Deployment

# Deploy to Oracle Cloud Free Tier
chmod +x scripts/deploy-oracle.sh
./scripts/deploy-oracle.sh

Manual Deployment Steps

1. Setup Oracle Cloud Account

   • Create free tier account
   • Setup compartment and VCN
   • Generate SSH keys

2. Deploy Instance

   # Using OCI CLI
   oci compute instance launch \
     --availability-domain <your-AD> \
     --compartment-id <compartment-id> \
     --shape VM.Standard.A1.Flex \
     --shape-config '{"memoryInGBs": "6", "ocpus": "2"}' \
     --display-name stock-valuation-mcp \
     --assign-public-ip true
   

3. Configure Environment

   # SSH into instance
   ssh -i ~/.ssh/oracle_key opc@<instance-ip>
   
   # Setup Docker
   sudo yum install -y docker
   sudo systemctl start docker
   sudo usermod -aG docker opc
   
   # Deploy MCP Server
   docker run -d \
     --name stock-valuation-mcp \
     --restart unless-stopped \
     -p 2901:2901 \
     -e NODE_ENV=production \
     -e SET_WATCH_API_HOST=https://your-api.com \
     stock-valuation-mcp:latest
   

For detailed deployment instructions, see Oracle Cloud Deployment Guide.

---

🔗 n8n Integration

Setting up n8n

1. Deploy n8n

   docker-compose up -d
   

2. Create HTTP Request Node

   {
     "method": "POST",
     "url": "http://YOUR-MCP-SERVER:2901/mcp",
     "body": {
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "fetch_stock_data",
         "arguments": {
           "symbol": "ADVANC"
         }
       }
     }
   }
   

Example Workflows

• Daily Analysis Report: Automatically analyze portfolio stocks every morning
• Price Alerts: Get notified when stocks hit target prices
• Batch Valuation: Value multiple stocks in parallel

For complete n8n integration guide, see n8n Integration Documentation.

---

📚 Documentation

Document	Description
Oracle Cloud Deployment	Complete guide for deploying to Oracle Cloud Free Tier
n8n Integration	Integrate with n8n for automated workflows
n8n API Examples	Ready-to-use n8n workflow examples
Troubleshooting	Common issues and solutions

---

⚙️ Installation

Development Mode

# Install dependencies
npm install

# Set up environment
cp .env.example .env

# Build TypeScript
npm run build

# Run in development
npm run dev

Production Mode

# Build for production
npm run clean
npm run build

# Run production server
npm start

Docker Deployment

# Build image
docker build -t stock-valuation-mcp .

# Run with Docker
docker run -d \
  -p 2901:2901 \
  -e NODE_ENV=production \
  stock-valuation-mcp

# Or use Docker Compose
docker-compose up -d

---

🔧 Configuration

Environment Variables

Create a .env file based on .env.example:

# API Configuration
SET_WATCH_API_HOST=https://xxxxxxxxxxxx.app  # Your API host
SET_WATCH_API_TIMEOUT=30000

# Server Configuration
NODE_ENV=production
LOG_LEVEL=info

# Optional: Custom API Authentication
# API_AUTH_HEADER=X-API-Key
# API_AUTH_VALUE=your-api-key

Available Variables

Variable	Description	Default
SET_WATCH_API_HOST	SET Watch API base URL	https://xxxx-api.vercel.app
SET_WATCH_API_TIMEOUT	API request timeout (ms)	30000
NODE_ENV	Environment mode	development
LOG_LEVEL	Logging level	info
API_AUTH_HEADER	Custom auth header	(none)
API_AUTH_VALUE	Auth header value	(none)

---

📚 API Documentation

Tool Examples

1. Complete Stock Analysis

{
  "tool": "complete_valuation",
  "arguments": {
    "symbol": "ADVANC",
    "requiredReturn": 0.10,
    "growthRate": 0.05,
    "discountRate": 0.10
  }
}

2. Financial Statement Analysis

{
  "tool": "fetch_all_financial_statements",
  "arguments": {
    "symbol": "SCB",
    "period": "Quarterly"
  }
}

3. Historical Trend Analysis

{
  "tool": "analyze_historical_ratios",
  "arguments": {
    "symbol": "PTT",
    "period": "Quarterly"
  }
}

Response Format

All tools return structured JSON responses including:

{
  "symbol": "ADVANC.BK",
  "timestamp": "2024-01-20T10:30:00Z",
  "data": { ... },
  "analysis": { ... },
  "recommendation": "Buy"
}

---

💡 Usage Examples

Example 1: Thai Stock Valuation

{
  "tool": "fetch_stock_data",
  "arguments": {
    "symbol": "AOT"
  }
}

Response: Current stock data with PE, PBV, EPS, dividend yield, ROE, etc.

Example 2: PE Band Analysis with Custom Data

{
  "tool": "calculate_pe_band",
  "arguments": {
    "symbol": "AAPL",
    "currentPrice": 150.00,
    "eps": 5.00,
    "historicalPEs": [15, 18, 20, 22, 25, 23]
  }
}

Response: PE band analysis with fair value range and recommendation.

Example 3: DCF Valuation

{
  "tool": "calculate_dcf",
  "arguments": {
    "symbol": "GOOGL",
    "currentPrice": 150,
    "freeCashFlow": 60000000000,
    "sharesOutstanding": 15000000000,
    "growthRate": 0.08,
    "discountRate": 0.10,
    "years": 5
  }
}

Response: DCF analysis with 5-year projections and intrinsic value calculation.

Example 4: Historical Ratio Analysis

{
  "tool": "analyze_historical_ratios",
  "arguments": {
    "symbol": "KBANK",
    "period": "Quarterly"
  }
}

Response: Complete historical analysis with trends and investment recommendation.

---

🚀 Deployment

Oracle Cloud Free Tier

1. Update Deployment Script:

   # Edit scripts/deploy-oracle.sh
   # Update your Oracle Cloud credentials
   

2. Deploy:

   chmod +x scripts/deploy-oracle.sh
   ./scripts/deploy-oracle.sh
   

3. Configure Environment:

   # On the instance
   docker pull <your-image>
   docker run -d \
     -p 2901:2901 \
     -e NODE_ENV=production \
     -e SET_WATCH_API_HOST=https://your-api.com \
     <your-image>
   

Docker Compose

services:
  stock-valuation:
    build: .
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - SET_WATCH_API_HOST=https://your-api.com
    ports:
      - "2901:2901"
    volumes:
      - ./logs:/app/logs

Environment-Specific Configuration

Development (.env.development):

NODE_ENV=development
LOG_LEVEL=debug
SET_WATCH_API_TIMEOUT=60000

Production (.env.production):

NODE_ENV=production
LOG_LEVEL=warn
SET_WATCH_API_TIMEOUT=10000

---

🏗️ Architecture

Project Structure

myMCPserver/
├── src/
│   ├── index.ts                    # Main MCP server entry point
│   ├── config/                     # Configuration management
│   │   └── index.ts               # Environment variable configuration
│   ├── types/                      # TypeScript type definitions
│   │   └── index.ts               # All type definitions
│   └── tools/                      # MCP tool implementations
│       ├── stockValuation.ts      # Core valuation models
│       ├── setWatchApi.ts         # SET Watch API integration
│       ├── financialStatements.ts # Financial statement tools
│       └── historicalRatios.ts     # Historical analysis tools
├── scripts/                         # Deployment scripts
├── dist/                           # Compiled TypeScript output
├── docs/                          # Additional documentation
├── tests/                         # Test files (when added)
├── docker-compose.yml              # Docker configuration
├── Dockerfile                      # Docker image definition
├── .env.example                    # Environment variable template
└── README.md                      # This file

MCP Server Architecture

┌─────────────────────────────────────┐
│           Claude Desktop              │
│                │                    │
│         MCP Protocol                 │
│                │                    │
├─────────────────────────────────────┤
│         Stock Valuation Server       │
│  ┌─────────────────────────────┐   │
│  │       Tool Registry          │   │
│  │  ┌─────────────────────────┐ │   │
│  │  │   Valuation Tools       │ │   │
│  │  │  Data Fetching Tools   │ │   │
│  │  │  Analysis Tools        │ │   │
│  │  └─────────────────────────┘ │   │
│  │          ┌─────────────────┐ │   │
│  │          │ Configuration   │ │   │
│  │          └─────────────────┘ │   │
│  └─────────────────────────────┘   │
│                │                    │
│          ┌─────────────────┐      │
│          │  SET Watch API     │◄────┘
│          └─────────────────┘      │
└─────────────────────────────────────┘

---

🤝 Contributing

We welcome contributions! Please follow these steps:

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Ensure all tests pass (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Create a Pull Request

Code Standards

• Use TypeScript for all new code
• Follow ESLint rules (npm run lint)
• Add JSDoc comments for functions
• Write tests for new features
• Update documentation

Testing

# Run unit tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏‍♂️ Acknowledgments

• Model Context Protocol - For the MCP SDK
• SET Watch - For providing the Thai stock market data API
• Oracle Cloud - For the generous free tier hosting option
• n8n - For workflow automation capabilities

---

📞 Support

• 📧 Create an issue for bug reports or feature requests
• 📖 Check Issues for known problems
• 📚 See Documentation for detailed guides

---

<div align="center"> <strong>Built with ❤️ for the investment community</strong> </div>