Forecast Storage MCP Server

How to use

You interact with the Forecast Storage MCP Server through an MCP client to upload complete forecasts (text and optional audio), fetch cached forecasts, and manage storage. Key workflows include storing a new forecast for a city, retrieving the latest cached forecast when available, cleaning up expired forecasts, listing forecast history, and checking storage statistics.

Typical actions you perform from your MCP client: - Upload a forecast for a city with its text, optional audio, timestamps, language, and locale. - Retrieve a cached forecast to minimize repeated processing or external lookups. - Clean up forecasts that have expired according to their TTL. - Inspect storage statistics to see total forecasts, encodings, languages used, and per-city breakdowns. - List forecast history for auditing or debugging purposes.

How to install

Prerequisites you should have before starting:
- Python 3.8+ and pip for dependency management.
- Access to a Google Cloud SQL PostgreSQL instance or the ability to create one.
- Cloud SQL client tools or environment setup to reach the Cloud SQL instance securely.

# Step 1: Create a Cloud SQL PostgreSQL instance (example shown using gcloud)
gcloud sql instances create weather-forecasts \
  --database-version=POSTGRES_17 \
  --tier=db-f1-micro \
  --region=us-central1 \
  --enable-auto-scaling \
  --auto-scaling-min-cpu=1 \
  --auto-scaling-max-cpu=2

# Step 2: Create the database
gcloud sql databases create weather \
  --instance=weather-forecasts

# Step 3: Set the postgres user password
gcloud sql users set-password postgres \
  --instance=weather-forecasts \
  --password=YOUR_SECURE_PASSWORD

Step 4: Apply the database schema to prepare the forecasts table and supporting structures. You can obtain the instance IP and then apply the schema file against the weather database.

# Get the instance IP
gcloud sql instances describe weather-forecasts --format="value(ipAddresses[0].ipAddress)"

# Apply schema
psql -h INSTANCE_IP -U postgres -d weather -f schema.sql

Step 5: Configure environment for the server by copying the example environment file, then editing values specific to your GCP project and Cloud SQL password.

# Copy example environment file
cp .env.example .env

# Edit .env with your values
# GCP_PROJECT_ID=your-project-id
# CLOUD_SQL_PASSWORD=your-secure-password

Step 6: Install dependencies and start the MCP server.

pip install -r requirements.txt

# Run the MCP server
python server.py

Additional configuration and usage notes

Configuration relies on a Cloud SQL PostgreSQL backend with encoding options and TTL-based caching. The server supports binary storage for text and audio with Unicode support and automatic encoding detection. You can set the encoding preference (default utf-8) and rely on auto-detection if not specified.

Environment variables you will typically configure include the Google Cloud project ID and the Cloud SQL password. These values enable the server to connect securely to Cloud SQL.

Common commands you will use from your MCP client are described in the MCP Tools section and include uploading forecasts, retrieving cached forecasts, cleaning expired data, listing history, and querying storage statistics.

Security and maintenance

Keep your Cloud SQL password and project credentials secure. Use least-privilege access for service accounts and ensure network access to Cloud SQL is restricted to trusted clients or private networks. Regularly review TTL settings and archive or delete forecasts past their retention window.

Troubleshooting

If you encounter connection issues, verify that the Cloud SQL instance is running, firewall rules permit connections from your environment, and credentials in your environment file are correct. Use the test connection workflow from your MCP client to validate reachability and credentials.

If encoding problems arise, confirm the encoding preference and rely on automatic detection when not specified. UTF-8 works for most languages; use UTF-16 for heavy CJK text.

Cost considerations

Development using a small Cloud SQL instance and modest storage incurs a low monthly cost. For production workloads, consider a larger instance and increased storage to meet performance and retention requirements.

Estimate costs for your region and usage patterns based on Cloud SQL pricing and storage needs.

Notes

This server stores forecasts in a PostgreSQL database with binary text and audio, includes per-city statistics, and supports internationalization across languages and locales.

upload_forecast

Uploads a complete forecast including text and optional audio to Cloud SQL, with metadata such as city, language, locale, and TTL.

get_cached_forecast

Retrieves a cached forecast for a city in a specific language if it exists and is not expired, returning text and base64-encoded audio.

cleanup_expired_forecasts

Removes forecasts from the database that have expired according to their TTL.

get_storage_stats

Returns storage statistics including total forecasts, encoding usage, languages, and per-city breakdown.

list_forecasts

Lists forecast history for a given city with pagination support.

test_connection

Tests the database connection to ensure the MCP server can reach Cloud SQL.