Configuration

ByteMCP uses environment variables for configuration. This guide covers all available options.

Environment Variables

Required: Database Connection

# MySQL Database (Required)
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=bytefederal
DB_USER=your_username
DB_PASSWORD=your_password

Server Mode

# MCP Mode: 'stdio' (default) or 'remote'
MCP_MODE=stdio

# Port for remote mode (default: 3000)
PORT=3000

Optional: Geocoding

# Google Maps API key for address geocoding
# If not set, falls back to database city/state lookups
GEOCODING_API_KEY=your_google_maps_api_key

Optional: Heartbeat Monitoring

# Separate database for operations dashboard
HEARTBEAT_HOST=dashboard_host
HEARTBEAT_PORT=3306
HEARTBEAT_DATABASE=dashboard_db
HEARTBEAT_USER=dash_user
HEARTBEAT_PASSWORD=dash_pass

Operating Modes

stdio Mode (Default)

Standard input/output mode for local MCP clients like Claude Desktop.

# Run in stdio mode
npm start

# Or explicitly
MCP_MODE=stdio npm start

The server communicates via stdin/stdout using JSON-RPC messages.

Remote Mode

HTTP/SSE mode for cloud deployment and remote clients.

# Run in remote mode
npm run start:remote

# Or with environment variable
MCP_MODE=remote PORT=3030 npm start

Exposes HTTP endpoints for MCP communication.

Database Schema

ByteMCP expects a locations_map table with these columns:

Column	Type	Description
id	INT	Unique ATM identifier
name	VARCHAR	ATM/location name
address	VARCHAR	Street address
city	VARCHAR	City name
state	VARCHAR	State code (e.g., FL)
country	VARCHAR	Country code
lat	DECIMAL	Latitude
lon	DECIMAL	Longitude
google	VARCHAR	Google Maps link
google_dir	VARCHAR	Directions link
google_rev	VARCHAR	Reviews link
photo_url	VARCHAR	ATM photo URL
mo_open - sun_open	TIME	Opening hours by day
mo_close - sun_close	TIME	Closing hours by day

Connection Pooling

The database connection pool is configured with sensible defaults:

{
  connectionLimit: 10,
  waitForConnections: true,
  queueLimit: 0
}

Geocoding Fallback

If GEOCODING_API_KEY is not set, the server uses a fallback strategy:

1. Parse the location string for city/state
2. Query the database for average coordinates of ATMs in that area
3. Use those coordinates for distance calculations

This allows basic functionality without a Google Maps API key.

Security Considerations

• Never commit .env files to version control
• Use environment variables in production
• Restrict database user permissions to SELECT only
• Enable SSL for remote mode in production

Example Configurations

Development

DB_HOST=localhost
DB_DATABASE=bytefederal_dev
DB_USER=dev_user
DB_PASSWORD=dev_password
MCP_MODE=stdio

Production (Remote)

DB_HOST=db.example.com
DB_DATABASE=bytefederal
DB_USER=prod_user
DB_PASSWORD=secure_password
MCP_MODE=remote
PORT=3000
GEOCODING_API_KEY=your_api_key

Next Steps

• MCP Tools - Learn about available tools
• Local Deployment - Run locally
• Remote Deployment - Deploy as HTTP server