📊 Stock Valuation MCP Server

A comprehensive Model Context Protocol (MCP) server for professional stock valuation and financial analysis

📖 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

Setup Oracle Cloud Account
- Create free tier account
- Setup compartment and VCN
- Generate SSH keys

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

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

Deploy n8n
```
docker-compose up -d
```

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

Update Deployment Script:

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

Deploy:

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

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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests if applicable
Ensure all tests pass (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Built with ❤️ for the investment community