earth2-mcp-server

# Earth2 MCP Server Earth2 MCP Server enables Claude to access Earth2 account data, including properties, wallet information, transactions, and marketplace listings. Works with both **your own Earth2 credentials** or **Earthie platform credentials** as a fallback! ## Features - 🏠 **Property Management**: View and analyze Earth2 properties/tiles - 💰 **Wallet Access**: Check balance and wallet information - 📊 **Transaction History**: Review Earth2 transactions - 🛒 **Marketplace**: Browse Earth2 marketplace listings - 💎 **Resources**: Access jewels, essence, and other resources - 📈 **Statistics**: Get detailed account statistics - 🔍 **Search**: Find properties by geographic location - 🔑 **Dual Credential Support**: Use your own credentials OR Earthie platform credentials - 🌐 **Web Integration**: Works in Earthie website chat interface - 💻 **Claude Desktop**: Full Claude Desktop support ## Installation ### From NPM (Recommended) ```bash npm install -g earth2-mcp-server ``` ### From Source ```bash git clone https://github.com/your-username/earth2-mcp-server.git cd earth2-mcp-server npm install npm link ``` ## Setup ### Getting Your Earth2 Credentials 1. **Login to Earth2**: - Go to [https://app.earth2.io](https://app.earth2.io) - Login with your credentials 2. **Extract XSRF Token**: - Open Developer Tools (F12 or Right-click → Inspect) - Go to the **Application** tab (Chrome) or **Storage** tab (Firefox) - Navigate to **Cookies** → `https://app.earth2.io` - Find and copy the value of `XSRF-TOKEN` 3. **Extract Session Cookie**: - In the same Cookies section - Copy the entire cookie string (you'll need the session cookie name and value) ### Configure Environment Variables (Optional) **Option 1: Use Your Own Credentials** Create a `.env` file in the earth2-mcp-server directory: ```env EARTH2_XSRF_TOKEN=your_xsrf_token_here EARTH2_COOKIE=your_session_cookie_here ``` **Option 2: Use Earthie Platform Credentials (Easiest!)** No configuration needed! The server automatically falls back to Earthie's credentials if your own aren't provided. You can also explicitly set: ```env EARTHIE_XSRF_TOKEN=provided_by_earthie EARTHIE_COOKIE=provided_by_earthie ``` Or use the hardcoded values from Earthie: ```env HARDCODED_CSRF=from_earthie_env HARDCODED_COOKIE=from_earthie_env ``` ## Usage ### With Claude Desktop **See [CLAUDE_DESKTOP_SETUP.md](./CLAUDE_DESKTOP_SETUP.md) for complete configuration guide!** **Quick Setup with Earthie Credentials:** ```json { "mcpServers": { "earth2": { "command": "npx", "args": ["-y", "earth2-mcp-server"], "env": { "EARTHIE_XSRF_TOKEN": "your_token", "EARTHIE_COOKIE": "your_cookie" } } } } ``` **Or use your own credentials:** ```json { "mcpServers": { "earth2": { "command": "npx", "args": ["-y", "earth2-mcp-server"], "env": { "EARTH2_XSRF_TOKEN": "your_token", "EARTH2_COOKIE": "your_cookie" } } } } ``` Then restart Claude Desktop. ### With Claude Online (HTTP Mode) 1. **Start the HTTP server**: ```bash cd earth2-mcp-server npm run start:http ``` 2. **Configure your credentials**: - Visit `http://localhost:3002/auth.html` - Enter your XSRF Token and Session Cookie - Complete the authentication flow 3. **Connect in Claude Online**: - Add the MCP server URL: `http://localhost:3002/mcp` - Use the authorization token provided after authentication ## Available Tools ### `get_profile` Get your Earth2 user profile information. ``` Get my Earth2 profile ``` ### `get_properties` Get all your Earth2 properties/tiles. ``` Show me all my Earth2 properties ``` ### `get_wallet` Get your Earth2 wallet balance and information. ``` What's my Earth2 wallet balance? ``` ### `get_transactions` Get your Earth2 transaction history. Parameters: - `limit` (optional): Number of transactions to retrieve (default: 50) ``` Show my last 100 Earth2 transactions ``` ### `get_marketplace` Browse Earth2 marketplace listings. Parameters: - `country` (optional): Filter by country code (e.g., 'US', 'GB') - `min_price` (optional): Minimum price filter - `max_price` (optional): Maximum price filter - `sort` (optional): Sort order (price_asc, price_desc, date_desc, date_asc) ``` Show me Earth2 marketplace listings in the US under $100 ``` ### `get_property_details` Get detailed information about a specific property. Parameters: - `property_id` (required): The property ID to get details for ``` Get details for property ID abc123 ``` ### `get_jewels` Get your Earth2 jewels and resources. ``` What jewels do I have in Earth2? ``` ### `get_essence` Get your Earth2 essence information. ``` Show me my essence in Earth2 ``` ### `get_stats` Get your Earth2 account statistics. ``` What are my Earth2 account stats? ``` ### `search_properties` Search for properties by geographic location. Parameters: - `latitude` (required): Latitude coordinate - `longitude` (required): Longitude coordinate - `radius` (optional): Search radius in meters (default: 1000) ``` Find Earth2 properties near latitude 40.7128, longitude -74.0060 ``` ## Example Conversations ### Check Your Portfolio ``` You: What properties do I own in Earth2? Claude: [Uses get_properties tool to show your properties] You: What's the total value of my portfolio? Claude: [Analyzes the property data and calculates total value] ``` ### Marketplace Research ``` You: Show me the cheapest properties available in Japan Claude: [Uses get_marketplace with country filter and price sorting] You: What's the average price for tiles in that area? Claude: [Analyzes marketplace data to calculate average] ``` ### Transaction Analysis ``` You: What were my biggest Earth2 purchases this month? Claude: [Uses get_transactions and analyzes the data] ``` ## Security Notes - **Credential Safety**: Your XSRF token and session cookie are sensitive credentials. Never share them publicly. - **Session Expiration**: These credentials will expire when you logout from Earth2. You'll need to get new ones. - **Local Storage**: Credentials are stored only in your local `.env` file or Claude Desktop config. - **HTTPS Recommended**: For production use, run the HTTP server behind HTTPS proxy. ## Troubleshooting ### "Authentication failed" Error - Your credentials may have expired - Re-extract your XSRF token and session cookie from Earth2 - Update your `.env` file or Claude Desktop config ### "Earth2 API Error" Messages - Ensure you're logged into Earth2 in your browser - Check that your credentials are correctly copied (no extra spaces) - Verify the Earth2 API is accessible from your network ### Server Won't Start - Check that port 3002 is available (or change PORT in .env) - Ensure all dependencies are installed: `npm install` - Check logs for specific error messages ## Development ### Running in Development Mode ```bash npm run dev # Start stdio server with debugging npm run dev:http # Start HTTP server with debugging ``` ### Project Structure ``` earth2-mcp-server/ ├── server.mjs # Main MCP server (stdio) ├── http-server.mjs # HTTP wrapper for Claude Online ├── auth.html # OAuth authentication page ├── src/ │ └── earth2-client.mjs # Earth2 API client ├── package.json ├── .env # Your credentials (gitignored) └── README.md ``` ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License MIT ## Disclaimer This is an unofficial third-party integration and is not affiliated with, endorsed by, or supported by Earth2.io. Use at your own risk. ## Support For issues and questions: - Email: philosncube@gmail.com --- Built with ❤️ for the Earth2 and Claude communities