Deployment Guide - YFinance MCP Server

Overview

The Financial MCP Server can be deployed to various platforms, from simple cloud services to enterprise Kubernetes clusters. This guide covers the most popular deployment options with step-by-step instructions.

Railway

Recommended for beginners

Zero-config deployment
Automatic scaling
Built-in monitoring

Docker

Flexible containerization

Platform independent
Easy scaling
Production ready

Railway Deployment (Recommended)

Railway offers the simplest deployment experience with automatic builds and scaling.

Prerequisites

GitHub account
Railway account (free tier available)
FMP API key (optional but recommended)

Step 1: Fork the Repository

Visit the GitHub repository
Click “Fork” to create your own copy
Clone your fork locally for any customizations

Step 2: Connect to Railway

Create Railway Project

Go to Railway
Sign up/login with GitHub
Click “New Project”
Select “Deploy from GitHub repo”
Choose your forked repository

Configure Environment Variables

In Railway dashboard, go to your project
Click “Variables” tab
Add the following variables:

FMP_API_KEY=your_actual_api_key_here
PORT=$PORT

Deploy

Railway automatically detects the Python app and deploys it using the Procfile.The deployment process:

Detects Python runtime
Installs dependencies from requirements.txt
Runs the command from Procfile
Assigns a public URL

Step 3: Verify Deployment

# Test your deployed server
curl "https://your-app-name.railway.app/api/v1/health"

# Expected response
{
  "status": "healthy",
  "tools_available": 32,
  "data_sources": ["YFinance", "FMP"],
  "timestamp": "2025-06-28T18:42:12.471731"
}

Railway Configuration

{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

web: python main.py

fastapi==0.104.1
uvicorn==0.24.0
yfinance==0.2.18
requests==2.31.0
python-dotenv==1.0.0
mcp==0.9.0

Docker Deployment

Docker provides a consistent deployment environment across different platforms.

Prerequisites

Docker installed
Docker Hub account (for image hosting)
Basic Docker knowledge

Step 1: Build Docker Image

FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Copy requirements first for better caching
COPY requirements.txt .

# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose port
EXPOSE 8001

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8001/api/v1/health || exit 1

# Run the application
CMD ["python", "main.py"]

# Build the image
docker build -t financial-mcp-server .

# Run locally
docker run -p 8001:8001 \
  -e FMP_API_KEY=your_api_key \
  financial-mcp-server

# Test the container
curl "http://localhost:8001/api/v1/health"

Step 2: Docker Compose (Recommended)

version: '3.8'

services:
  financial-mcp:
    build: .
    ports:
      - "8001:8001"
    environment:
      - FMP_API_KEY=${FMP_API_KEY}
      - PORT=8001
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8001/api/v1/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # Optional: Add reverse proxy
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - financial-mcp
    restart: unless-stopped

# Create .env file
echo "FMP_API_KEY=your_actual_api_key" > .env

# Start services
docker-compose up -d

# View logs
docker-compose logs -f financial-mcp

# Stop services
docker-compose down

Step 3: Production Docker Setup

# Optimized Dockerfile for production
FROM python:3.11-slim as builder

WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

FROM python:3.11-slim

# Create non-root user
RUN useradd --create-home --shell /bin/bash app

# Copy installed packages
COPY --from=builder /root/.local /home/app/.local
COPY --chown=app:app . /home/app/

WORKDIR /home/app
USER app

# Make sure scripts are in PATH
ENV PATH=/home/app/.local/bin:$PATH

EXPOSE 8001
CMD ["python", "main.py"]

# Tag for Docker Hub
docker tag financial-mcp-server username/financial-mcp-server:latest

# Push to Docker Hub
docker push username/financial-mcp-server:latest

# Deploy anywhere
docker run -d \
  --name financial-mcp \
  -p 8001:8001 \
  -e FMP_API_KEY=your_key \
  --restart unless-stopped \
  username/financial-mcp-server:latest

Heroku Deployment

Heroku provides a simple platform-as-a-service solution.

Prerequisites

Heroku account
Heroku CLI installed
Git repository

Deployment Steps

Prepare Application

Ensure your repository has the required files:

├── main.py
├── requirements.txt
├── Procfile
└── runtime.txt (optional)

Create Heroku App

# Login to Heroku
heroku login

# Create new app
heroku create your-financial-mcp-server

# Set environment variables
heroku config:set FMP_API_KEY=your_actual_api_key

Deploy

# Add Heroku remote
heroku git:remote -a your-financial-mcp-server

# Deploy
git push heroku main

# Open in browser
heroku open

Heroku Configuration

web: python main.py

python-3.11.6

# View logs
heroku logs --tail

# Scale dynos
heroku ps:scale web=1

# Check status
heroku ps

# Set config vars
heroku config:set FMP_API_KEY=new_key

VPS/Cloud Server Deployment

Deploy to any cloud server (AWS EC2, DigitalOcean, Linode, etc.).

Prerequisites

Ubuntu/Debian server
SSH access
Domain name (optional)

Step 1: Server Setup

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python and dependencies
sudo apt install python3 python3-pip python3-venv nginx git -y

# Create application user
sudo useradd -m -s /bin/bash financial-mcp
sudo su - financial-mcp

# Clone repository
git clone https://github.com/your-username/yfi-deployment.git
cd yfi-deployment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
echo "export FMP_API_KEY='your_actual_api_key'" >> ~/.bashrc
echo "export PORT=8001" >> ~/.bashrc
source ~/.bashrc

Step 2: Process Management

# Create /etc/systemd/system/financial-mcp.service
[Unit]
Description=Financial MCP Server
After=network.target

[Service]
Type=simple
User=financial-mcp
WorkingDirectory=/home/financial-mcp/yfi-deployment
Environment=PATH=/home/financial-mcp/yfi-deployment/venv/bin
Environment=FMP_API_KEY=your_actual_api_key
Environment=PORT=8001
ExecStart=/home/financial-mcp/yfi-deployment/venv/bin/python main.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable financial-mcp
sudo systemctl start financial-mcp

# Check status
sudo systemctl status financial-mcp

# View logs
sudo journalctl -u financial-mcp -f

Step 3: Reverse Proxy (Nginx)

# /etc/nginx/sites-available/financial-mcp
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Enable site
sudo ln -s /etc/nginx/sites-available/financial-mcp /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Restart nginx
sudo systemctl restart nginx

# Optional: Setup SSL with Let's Encrypt
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d your-domain.com

Kubernetes Deployment

For enterprise deployments requiring high availability and scaling.

Prerequisites

Kubernetes cluster
kubectl configured
Basic Kubernetes knowledge

Deployment Manifests

apiVersion: apps/v1
kind: Deployment
metadata:
  name: financial-mcp-server
  labels:
    app: financial-mcp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: financial-mcp
  template:
    metadata:
      labels:
        app: financial-mcp
    spec:
      containers:
      - name: financial-mcp
        image: username/financial-mcp-server:latest
        ports:
        - containerPort: 8001
        env:
        - name: FMP_API_KEY
          valueFrom:
            secretKeyRef:
              name: financial-mcp-secret
              key: fmp-api-key
        - name: PORT
          value: "8001"
        livenessProbe:
          httpGet:
            path: /api/v1/health
            port: 8001
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /api/v1/health
            port: 8001
          initialDelaySeconds: 5
          periodSeconds: 5

---
apiVersion: v1
kind: Service
metadata:
  name: financial-mcp-service
spec:
  selector:
    app: financial-mcp
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8001
  type: ClusterIP

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: financial-mcp-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts:
    - api.your-domain.com
    secretName: financial-mcp-tls
  rules:
  - host: api.your-domain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: financial-mcp-service
            port:
              number: 80

Kubernetes Commands

# Create secret for API key
kubectl create secret generic financial-mcp-secret \
  --from-literal=fmp-api-key=your_actual_api_key

# Apply manifests
kubectl apply -f k8s/

# Check deployment
kubectl get deployments

# View pods
kubectl get pods

# Check logs
kubectl logs -l app=financial-mcp

# Scale deployment
kubectl scale deployment financial-mcp-server --replicas=5

Monitoring & Maintenance

Health Monitoring

# Basic health check
curl -f https://your-domain.com/api/v1/health

# Detailed monitoring script
#!/bin/bash
ENDPOINT="https://your-domain.com/api/v1/health"
RESPONSE=$(curl -s $ENDPOINT)
STATUS=$(echo $RESPONSE | jq -r '.status')

if [ "$STATUS" != "healthy" ]; then
    echo "Server unhealthy: $RESPONSE"
    # Send alert (email, Slack, etc.)
fi

# Simple Python monitoring script
import requests
import time
import logging

def check_health():
    try:
        response = requests.get("https://your-domain.com/api/v1/health", timeout=10)
        if response.status_code == 200:
            data = response.json()
            logging.info(f"Server healthy: {data['tools_available']} tools available")
            return True
        else:
            logging.error(f"Health check failed: {response.status_code}")
            return False
    except Exception as e:
        logging.error(f"Health check exception: {e}")
        return False

# Run every 5 minutes
while True:
    check_health()
    time.sleep(300)

Log Management

# Setup logrotate for application logs
sudo cat > /etc/logrotate.d/financial-mcp << EOF
/var/log/financial-mcp/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 644 financial-mcp financial-mcp
    postrotate
        systemctl reload financial-mcp
    endscript
}
EOF

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_entry = {
            "timestamp": datetime.utcnow().isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno
        }
        return json.dumps(log_entry)

# Configure logging
handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logger = logging.getLogger()
logger.addHandler(handler)
logger.setLevel(logging.INFO)

Troubleshooting

Common Deployment Issues

Port Already in Use

Error: [Errno 48] error while attempting to bind on address ('0.0.0.0', 8001): [errno 48] address already in useSolutions:

# Find process using port
lsof -i :8001

# Kill process
kill -9 <PID>

# Or use different port
export PORT=8002

Environment Variables Not Loading

Error: Server uses demo API key despite setting FMP_API_KEYSolutions:

# Verify environment variables
printenv | grep FMP

# Restart service after setting variables
sudo systemctl restart financial-mcp

# Check service environment
sudo systemctl show financial-mcp --property=Environment

Docker Container Exits

Error: Container exits immediately after startingSolutions:

# Check container logs
docker logs container-name

# Run interactively for debugging
docker run -it --entrypoint /bin/bash financial-mcp-server

# Check if all dependencies are installed
docker run financial-mcp-server pip list

Performance Optimization

Production Optimizations

# Use connection pooling
import aiohttp
import asyncio

# Global session with connection pooling
session = aiohttp.ClientSession(
    connector=aiohttp.TCPConnector(
        limit=100,
        limit_per_host=30,
        keepalive_timeout=30
    )
)

# Implement caching
from functools import lru_cache
import time

@lru_cache(maxsize=1000)
def get_cached_data(symbol: str, minute: int):
    # Cache data for 1-minute intervals
    return fetch_data(symbol)

# Docker resource limits
docker run -d \
  --name financial-mcp \
  --memory=512m \
  --cpus=1.0 \
  -p 8001:8001 \
  financial-mcp-server

# Kubernetes resource limits
resources:
  limits:
    memory: "512Mi"
    cpu: "500m"
  requests:
    memory: "256Mi"
    cpu: "250m"

Next Steps

Monitoring Setup

Set up comprehensive monitoring and alerting

Security Guide

Implement security best practices

Scaling Guide

Handle high-traffic scenarios

API Documentation

Explore all available endpoints

​Overview

Railway

Docker

​Railway Deployment (Recommended)

​Prerequisites

​Step 1: Fork the Repository

​Step 2: Connect to Railway

​Step 3: Verify Deployment

​Railway Configuration

​Docker Deployment

​Prerequisites

​Step 1: Build Docker Image

​Step 2: Docker Compose (Recommended)

​Step 3: Production Docker Setup

​Heroku Deployment

​Prerequisites

​Deployment Steps

​Heroku Configuration

​VPS/Cloud Server Deployment

​Prerequisites

​Step 1: Server Setup

​Step 2: Process Management

​Step 3: Reverse Proxy (Nginx)

​Kubernetes Deployment

​Prerequisites

​Deployment Manifests

​Kubernetes Commands

​Monitoring & Maintenance

​Health Monitoring

​Log Management

​Troubleshooting

​Common Deployment Issues

​Performance Optimization

​Production Optimizations

​Next Steps

Monitoring Setup

Security Guide

Scaling Guide

API Documentation

Overview

Railway Deployment (Recommended)

Prerequisites

Step 1: Fork the Repository

Step 2: Connect to Railway

Step 3: Verify Deployment

Railway Configuration

Docker Deployment

Prerequisites

Step 1: Build Docker Image

Step 2: Docker Compose (Recommended)

Step 3: Production Docker Setup

Heroku Deployment

Prerequisites

Deployment Steps

Heroku Configuration

VPS/Cloud Server Deployment

Prerequisites

Step 1: Server Setup

Step 2: Process Management

Step 3: Reverse Proxy (Nginx)

Kubernetes Deployment

Prerequisites

Deployment Manifests

Kubernetes Commands

Monitoring & Maintenance

Health Monitoring

Log Management

Troubleshooting

Common Deployment Issues

Performance Optimization

Production Optimizations

Next Steps