# MCP Client Setup Guide
This is a **detailed reference guide** for configuring the Malaysian Weather MCP Server with different MCP clients.
**For a quick start**, see [README.md](README.md) which has a complete 5-minute setup guide.
This guide explains how to install and configure this MCP server with various clients (Claude Desktop, Cline, etc.).
## Table of Contents
1. [Claude Desktop](#claude-desktop) (Recommended)
2. [Cline VSCode Extension](#cline-vscode-extension)
3. [Other MCP Clients](#other-mcp-clients)
4. [Local Server Setup](#local-server-setup)
5. [Troubleshooting](#troubleshooting)
---
## Claude Desktop
Claude Desktop is the official desktop application from Anthropic that supports MCP servers.
### Installation
1. **Install Claude Desktop** (if not already installed):
- Download from https://claude.ai/desktop
- Install and launch the application
2. **Clone or install Weather-by-Met**:
```bash
git clone https://github.com/zhenkai-dev/weather-by-met.git
cd weather-by-met
pip install -r requirements.txt
```
3. **Set up database** (see [Local Server Setup](#local-server-setup) below)
4. **Configure MCP in Claude Desktop**:
**macOS**:
```bash
# Edit the configuration file
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Windows**:
```
Open: %APPDATA%\Claude\claude_desktop_config.json
```
**Linux**:
```bash
nano ~/.config/Claude/claude_desktop_config.json
```
5. **Add MCP Server Configuration**:
```json
{
"mcpServers": {
"weather-malaysia": {
"command": "python",
"args": ["/path/to/weather-by-met/server.py"],
"env": {
"DB_HOST": "localhost",
"DB_USER": "root",
"DB_PASSWORD": "your_mysql_password",
"DB_NAME": "weather_by_met"
}
}
}
}
```
**Important**: Replace `/path/to/weather-by-met/` with the actual installation path:
- **macOS Example**: `/Users/john/weather-by-met/server.py`
- **Windows Example**: `C:\Users\john\weather-by-met\server.py`
- **Linux Example**: `/home/john/weather-by-met/server.py`
6. **Verify Path** (Important!):
```bash
# Verify the path exists
ls -la /path/to/weather-by-met/server.py
```
7. **Restart Claude Desktop**:
- Completely close Claude Desktop
- Reopen the application
- The MCP server should now be available
8. **Test the Connection**:
- In Claude, try asking: "What's the weather in Kuala Lumpur?"
- If successful, Claude will use the weather tools to fetch data
---
## Cline VSCode Extension
Cline is a VSCode extension that supports MCP servers for AI-powered coding assistance.
### Installation
1. **Install Cline Extension**:
- Open VSCode
- Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
- Search for "Cline"
- Install the extension
2. **Install Weather-by-Met**:
```bash
git clone https://github.com/zhenkai-dev/weather-by-met.git
cd weather-by-met
pip install -r requirements.txt
```
3. **Set up database** (see [Local Server Setup](#local-server-setup) below)
4. **Configure Cline**:
- Click the Cline icon in VSCode sidebar
- Open Settings/Preferences
- Find "MCP Servers" section
- Click "Add MCP Server"
5. **Add Weather-by-Met Configuration**:
```json
{
"type": "stdio",
"command": "python",
"args": ["/path/to/weather-by-met/server.py"],
"env": {
"DB_HOST": "localhost",
"DB_USER": "root",
"DB_PASSWORD": "your_mysql_password",
"DB_NAME": "weather_by_met"
},
"name": "weather-malaysia"
}
```
6. **Save and Restart Cline**
7. **Use in Cline**:
- In Cline chat, you can now ask about Malaysian weather
- Example: "Create a weather dashboard for Malaysian cities"
---
## Other MCP Clients
Any MCP-compliant client can use this server. Examples include:
- **Cursor IDE**
- **Zed Editor**
- **Custom Applications** using MCP SDKs
- **Web-based Clients**
### Generic Configuration Format
Most MCP clients use this standard format:
```json
{
"transport": {
"type": "stdio"
},
"command": "python",
"args": ["/path/to/weather-by-met/server.py"],
"environment": {
"DB_HOST": "localhost",
"DB_USER": "root",
"DB_PASSWORD": "your_mysql_password",
"DB_NAME": "weather_by_met"
}
}
```
Refer to your specific client's documentation for exact configuration steps.
---
## Local Server Setup
This section covers setting up the weather server and database locally.
### Prerequisites
- Python 3.8+
- MySQL 8.0+
- pip
### Step 1: Clone the Repository
```bash
git clone https://github.com/zhenkai-dev/weather-by-met.git
cd weather-by-met
```
### Step 2: Create Python Virtual Environment
```bash
# Create virtual environment
python -m venv venv
# Activate it
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate
```
### Step 3: Install Dependencies
```bash
pip install -r requirements.txt
```
### Step 4: Configure Database
1. **Create .env file**:
```bash
cp .env.example .env
```
2. **Edit .env** with your MySQL credentials:
```bash
# macOS/Linux:
nano .env
# Windows (use Notepad or your editor):
```
3. **Example .env**:
```
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_strong_password_here
DB_NAME=weather_by_met
DB_PORT=3306
```
### Step 5: Initialize Database
```bash
python init_db.py
```
This will:
- Create the `weather_by_met` database
- Create the `weather_forecasts` table
- Set up proper indexes and constraints
### Step 6: Start the Scheduler (Optional but Recommended)
The scheduler automatically fetches weather data every 15 minutes:
```bash
python scheduler.py
```
This will run in the foreground. To run in the background:
**macOS/Linux**:
```bash
nohup python scheduler.py > scheduler_output.log 2>&1 &
```
**Windows** (in PowerShell):
```powershell
Start-Process python -ArgumentList "scheduler.py" -WindowStyle Hidden
```
### Step 7: Test the Server
In another terminal:
```bash
python server.py
```
The server should start without errors. Now you're ready to configure it with your MCP client!
---
## Troubleshooting
### Server Not Connecting
**Symptom**: Claude doesn't see the weather tools
**Solutions**:
1. **Check file path**:
```bash
# Verify the path exists and is absolute
ls -la /path/to/weather-by-met/server.py
# Don't use relative paths like ~/weather-by-met/server.py
# Use absolute paths like /Users/username/weather-by-met/server.py
```
2. **Check Python availability**:
```bash
# Verify Python can import required packages
python -c "import fastmcp; print('OK')"
```
3. **Verify database connection**:
```bash
# Test MySQL connection
python init_db.py
```
4. **Check logs** (if running scheduler):
```bash
tail -f weather_scheduler.log
```
5. **Restart the MCP client**:
- Completely close the application
- Reopen it
- Check if tools appear now
### Database Connection Error
**Symptom**: "Database connection failed" or "Authentication failed"
**Solutions**:
1. **Verify MySQL is running**:
```bash
# macOS:
brew services list | grep mysql
# Linux:
sudo systemctl status mysql
# Windows: Check Services in Task Manager
```
2. **Test connection manually**:
```bash
mysql -u root -p -h localhost
# Enter your password
```
3. **Check .env credentials**:
```bash
cat .env
# Verify DB_HOST, DB_USER, DB_PASSWORD are correct
```
4. **Create database user** (if needed):
```sql
CREATE USER 'weather_user'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON weather_by_met.* TO 'weather_user'@'localhost';
FLUSH PRIVILEGES;
```
### No Weather Data
**Symptom**: Tool runs but returns "No data available"
**Solutions**:
1. **Check scheduler is running**:
```bash
# Is it running?
ps aux | grep scheduler.py
# If not, start it:
python scheduler.py
```
2. **Check database has data**:
```bash
mysql -u root -p weather_by_met
# SELECT COUNT(*) FROM weather_forecasts;
```
3. **Wait for first data fetch**:
- The scheduler fetches data every 15 minutes
- First fetch might take a minute or two
- Check logs: `tail -f weather_scheduler.log`
### Claude Says "Tool Not Found"
**Symptom**: Claude sees the MCP server but tools aren't available
**Solutions**:
1. **Verify server.py is valid**:
```bash
python server.py # Should start without errors
```
2. **Check for syntax errors**:
```bash
python -m py_compile server.py
```
3. **Restart Claude Desktop completely**:
- Force quit (Cmd+Q / Ctrl+Q)
- Wait 5 seconds
- Reopen
4. **Check the configuration file syntax**:
```bash
# Verify JSON is valid
python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
### Permission Denied Error
**Symptom**: "Permission denied" when trying to run server.py
**Solutions**:
```bash
# Make script executable
chmod +x /path/to/weather-by-met/server.py
# Restart client
```
### Still Having Issues?
1. **Check Claude Desktop logs**:
- macOS: `~/Library/Logs/Claude/`
- Windows: `%APPDATA%\Claude\Logs\`
- Linux: `~/.config/Claude/logs/`
2. **Open a GitHub Issue**:
- Include error messages
- Include environment details (OS, Python version, etc.)
- Include steps to reproduce
3. **Test components individually**:
```bash
# Test database
python init_db.py
# Test server
python server.py
# Test scheduler
python scheduler.py
```
---
## Quick Reference
| Client | Config File | Transport | Status |
|--------|------------|-----------|--------|
| Claude Desktop | `claude_desktop_config.json` | stdio | ✅ Recommended |
| Cline VSCode | VSCode Settings | stdio | ✅ Works |
| Cursor IDE | Similar to Claude | stdio | ✅ Likely works |
| Custom Python | Varies | stdio/HTTP | ✅ Depends on SDK |
## Next Steps
- Read the main [README.md](README.md) for usage examples
- Check [CONTRIBUTING.md](CONTRIBUTING.md) if you want to contribute
- Explore the [code on GitHub](https://github.com/zhenkai-dev/weather-by-met)
Enjoy your Malaysian weather forecasts! 🌦️🇲🇾
