Weather MCP Server with GitHub OAuth & Location Management

# Weather MCP Server with GitHub OAuth & Location Management This project demonstrates an advanced Model Context Protocol (MCP) server with GitHub OAuth authentication, personalized location management, and weather data retrieval using Open-Meteo's free API. ## Features - **🔐 GitHub OAuth 2.0 Authentication**: Secure authentication using GitHub Apps - **📍 Personal Location Management**: Save and manage custom location labels (e.g., "home", "office") - **🌤️ Smart Weather Queries**: Check weather using saved labels or direct location names - **💾 SQLite Database**: Persistent storage for users and their locations - **🆓 Free Weather API**: Uses Open-Meteo API - no API key required! - **🔄 Streamable HTTP Transport**: Modern HTTP transport with MCP SDK - **🛠️ Multiple Tools**: Weather lookup, location management (add, list, delete), user info - **👤 User Profiles**: Automatic user creation from GitHub profile data with profile retrieval ## Prerequisites - Node.js (v18 or higher recommended) - GitHub Account - GitHub OAuth App (instructions below) - OpenAI API Key (optional, for the client example) ## Setup ### 1. Install dependencies: ```bash npm install ``` ### 2. Create GitHub OAuth App: 1. Go to [GitHub Developer Settings](https://github.com/settings/developers) 2. Click **"New OAuth App"** 3. Fill in the application details: - **Application name**: Weather MCP Server (or your preferred name) - **Homepage URL**: `http://localhost:3000` - **Authorization callback URL**: `http://localhost:3000/oauth/callback` 4. Click **"Register application"** 5. Copy your **Client ID** 6. Click **"Generate a new client secret"** and copy it ### 3. Configure Environment Variables: ```bash cp .env.example .env ``` Edit `.env` and add your GitHub OAuth credentials: ```bash GITHUB_CLIENT_ID=your_github_client_id_here GITHUB_CLIENT_SECRET=your_github_client_secret_here GITHUB_REDIRECT_URI=http://localhost:3000/oauth/callback PORT=3000 ``` ### 4. Start the MCP server: ```bash node server.js ``` The server will start on `http://127.0.0.1:3000` ### 5. Authenticate with GitHub: 1. Open your browser and visit: `http://localhost:3000/oauth/login` 2. Click **"Authorize"** to connect with GitHub 3. Copy the **access token** displayed on the success page 4. Use this token in the Authorization header: `Bearer <your-token>` ### 6. Configure Claude Desktop Add the configuration to your Claude Desktop config file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Option A: Automatic OAuth (Recommended)** ```json { "mcpServers": { "weather-server": { "command": "npx", "args": [ "-y", "mcp-remote", "http://127.0.0.1:3000/mcp" ] } } } ``` Claude Desktop will automatically discover the OAuth endpoints and open your browser for authentication. Just authorize with GitHub when prompted! **Option B: Manual Token** ```json { "mcpServers": { "weather-server": { "command": "npx", "args": [ "-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--header", "Authorization: Bearer YOUR_GITHUB_ACCESS_TOKEN", "--no-auth" ] } } } ``` First get your token by visiting `http://localhost:3000/oauth/login`, then replace `YOUR_GITHUB_ACCESS_TOKEN` with your token. ## Usage Examples Once connected via Claude Desktop, you can: ### Basic Weather Queries - "What is the weather like in San Francisco?" - "Tell me the current weather in Tokyo" - "How's the weather in Paris?" ### Save Personal Locations - "Save my home location as New York" - "Add my office location as San Francisco" - "Save the gym location as 123 Main Street, Boston" ### Query Using Saved Labels - "What's the weather at home?" - "How's the weather at the office?" - "Check the weather at the gym" ### Manage Locations - "List all my saved locations" - "Show my locations" - "Delete my home location" ### User Profile - "Who am I?" - "Show my profile" - "What's my GitHub username?" ## How It Works 1. **OAuth Flow**: User authenticates via GitHub OAuth 2.0 2. **Token Exchange**: Server exchanges authorization code for access token 3. **User Creation**: Server creates or updates user profile from GitHub data 4. **Authentication**: Client sends Bearer token in Authorization header 5. **Token Validation**: Server validates token against SQLite database 6. **Session Creation**: Server creates authenticated session with user context 7. **Tool Discovery**: Client discovers available MCP tools from server 8. **Tool Execution**: - Weather queries resolve location labels to actual addresses - Location management stores data per-user in database - All operations are scoped to the authenticated user 9. **Weather Data**: Server fetches real-time weather from Open-Meteo API 10. **Response**: Results returned to client with user-specific context ## Architecture ``` User Browser │ │ 1. Visit /oauth/login ▼ GitHub OAuth Server │ │ 2. Authorization ▼ /oauth/callback │ │ 3. Access Token ▼ ┌─────────────────────────────────────────────┐ │ Claude Desktop / MCP Client │ │ (with Authorization: Bearer token) │ └─────────────────┬───────────────────────────┘ │ Streamable HTTP + Auth ▼ ┌─────────────────────────────────────────────┐ │ server.js (MCP Server) │ │ ┌───────────────────────────────────────┐ │ │ │ OAuth Authentication (auth.js) │ │ │ │ ↓ │ │ │ │ Token Validation Middleware │ │ │ │ ↓ │ │ │ │ Session Management (per-user) │ │ │ │ ↓ │ │ │ │ MCP Tools: │ │ │ │ - get_current_weather │ │ │ │ - add_location │ │ │ │ - list_locations │ │ │ │ - delete_location │ │ │ └───────────────────────────────────────┘ │ │ ↓ │ │ ┌───────────────────────────────────────┐ │ │ │ SQLite Database (weather.db) │ │ │ │ - users (with GitHub data) │ │ │ │ - locations │ │ │ └───────────────────────────────────────┘ │ └─────────────────┬───────────────────────────┘ │ ▼ Open-Meteo Weather API ``` ## MCP Tools ### 1. `get_current_weather` Fetches real-time weather data for any location or saved label. - **Parameters**: - `location` (string): Location name or saved label (e.g., "New York", "home") - `unit` (enum): Temperature unit - "celsius" or "fahrenheit" (default: celsius) - **Returns**: Temperature, condition, humidity, wind speed, pressure, cloud cover - **Special**: Automatically resolves saved location labels to addresses ### 2. `add_location` Save a location with a custom label for quick access. - **Parameters**: - `label` (string): Custom label (e.g., "home", "office", "gym") - `location` (string): Actual location name or address - **Returns**: Confirmation message - **Note**: Replaces existing label if it already exists ### 3. `list_locations` Display all saved locations for the authenticated user. - **Parameters**: None - **Returns**: List of all saved locations with their labels ### 4. `delete_location` Remove a saved location by its label. - **Parameters**: - `label` (string): Label of the location to delete - **Returns**: Confirmation or error message ### 5. `get_user_info` Get information about the currently logged-in user. - **Parameters**: None - **Returns**: User profile with GitHub username, name, email, avatar URL, and user ID ## Project Structure ``` komunite-bootcamp-mcp/ ├── server.js # MCP HTTP server with OAuth ├── database.js # SQLite database operations ├── auth.js # GitHub OAuth authentication ├── index.js # OpenAI function calling example (legacy) ├── .env.example # Environment variables template ├── .env # Your environment variables (create this) ├── package.json # Dependencies and scripts ├── weather.db # SQLite database (created on first run) └── README.md # This file ``` ## Database Schema ### Users Table ```sql CREATE TABLE users ( id TEXT PRIMARY KEY, github_id TEXT UNIQUE, github_username TEXT, github_email TEXT, name TEXT, avatar_url TEXT, access_token TEXT, refresh_token TEXT, token_expires_at DATETIME, auth_token TEXT UNIQUE, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ``` ### Locations Table ```sql CREATE TABLE locations ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL, label TEXT NOT NULL, location_name TEXT NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, UNIQUE(user_id, label) ) ``` ## Security Features - **GitHub OAuth 2.0**: Industry-standard OAuth authentication flow - **PKCE (RFC 7636)**: Proof Key for Code Exchange with S256 for public clients - **Dynamic Client Registration (RFC 7591)**: Automatic client registration - **State Parameter**: CSRF protection with state verification - **Bearer Token Authentication**: All MCP endpoints require valid authentication - **Token Validation**: Access tokens validated against database - **User Isolation**: Each user can only access their own locations - **Session Management**: Secure session handling with user context - **Database Constraints**: Foreign key constraints ensure data integrity - **Automatic Token Expiration**: Token expiry tracking for enhanced security ## Customization ### Adding Custom MCP Tools 1. Open `server.js` 2. Register a new tool after existing tools: ```javascript sessionServer.tool( 'your_tool_name', 'Tool description', { param1: z.string().describe('Parameter description'), }, async ({ param1 }) => { const userId = sessionUsers[transport.sessionId]?.id; // Your tool logic here return { content: [{ type: 'text', text: 'Result' }], }; } ); ``` 3. The tool will automatically be discovered by clients ## API Endpoints ### OAuth Discovery Endpoints (RFC 8414 & RFC 9728) - **GET /.well-known/oauth-authorization-server** - OAuth 2.0 Authorization Server Metadata - **GET /.well-known/oauth-protected-resource** - OAuth 2.0 Protected Resource Metadata ### OAuth Endpoints (Standards-Compliant) - **POST /oauth/register** - Dynamic Client Registration (RFC 7591) - **GET /oauth/authorize** - OAuth 2.0 Authorization Endpoint - **POST /oauth/token** - OAuth 2.0 Token Endpoint - **POST /oauth/revoke** - OAuth 2.0 Token Revocation (RFC 7009) - **GET /oauth/login** - Manual OAuth flow (browser-based) - **GET /oauth/callback** - OAuth callback handler - **GET /oauth/me** - Returns current user info (requires authentication) ### MCP Endpoints - **POST /mcp** - Main MCP endpoint for tool calls - **GET /mcp** - Server-Sent Events for notifications - **DELETE /mcp** - Session termination ### Utility Endpoints - **GET /health** - Health check endpoint ## Notes - Based on the **Model Context Protocol (MCP)** specification - Uses **@modelcontextprotocol/sdk** for MCP server implementation - **Streamable HTTP transport**: Modern HTTP transport with session management - **SQLite Database**: Lightweight, file-based database with better-sqlite3 - **GitHub OAuth 2.0**: Secure authentication via GitHub Apps - Uses **Open-Meteo API** - free and open-source weather API - No API key required for weather data! - Per-user location management with database isolation - Automatic label resolution for convenient weather queries - User profiles automatically created from GitHub data ## Logout / Revoke Access To logout from OAuth when using Claude Desktop: ### Option 1: Clear mcp-remote Cache ```bash rm -rf ~/.cache/mcp-remote/auth/ ``` ### Option 2: Manual Token Revocation ```bash curl -X POST http://localhost:3000/oauth/revoke \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "token=YOUR_ACCESS_TOKEN" ``` Then clear the cache and restart Claude Desktop. ## Troubleshooting ### Token Expired If you get authentication errors, your GitHub token may have expired: 1. Visit `http://localhost:3000/oauth/login` again 2. Get a new access token 3. Update your Claude Desktop configuration with the new token ## Testing with cURL You can test the API directly with cURL: ```bash # Check OAuth server metadata: curl http://localhost:3000/.well-known/oauth-authorization-server # Check protected resource metadata: curl http://localhost:3000/.well-known/oauth-protected-resource # Get your access token first by visiting: open http://localhost:3000/oauth/login # Then test the authenticated endpoint: curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ http://localhost:3000/oauth/me ``` ## References - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [MCP Authorization Specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) - [OAuth 2.1 Draft Specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13) - [RFC 7009: OAuth 2.0 Token Revocation](https://datatracker.ietf.org/doc/html/rfc7009) - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) - [RFC 7636: PKCE - Proof Key for Code Exchange](https://datatracker.ietf.org/doc/html/rfc7636) - [RFC 8414: OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) - [GitHub OAuth Documentation](https://docs.github.com/en/developers/apps/building-oauth-apps) - [Open-Meteo Weather API](https://open-meteo.com/)