Axion Planetary MCP

<div align="center"> # 🌍 Axion Planetary MCP ## *The Foundation for Democratizing Geospatial AI Agents* --- ## 🚀 **V2.0 - Now Powered by AWS** > **Major Update:** Axion Planetary MCP has been completely rebuilt on AWS infrastructure for better performance, reliability, and global accessibility. No more Google Cloud setup required! --- [](https://www.youtube.com/watch?v=cd8twnn6en8) *Click the image above to watch the demo video* <img src="https://img.shields.io/npm/v/axion-mcp?style=for-the-badge&color=blue" alt="npm version" /> <img src="https://img.shields.io/badge/downloads-7%2C458%2Fmonth-green?style=for-the-badge" alt="downloads" /> <img src="https://img.shields.io/github/license/Dhenenjay/axion-planetary-mcp?style=for-the-badge&color=orange" alt="license" /> <img src="https://img.shields.io/badge/AWS-Powered-orange?style=for-the-badge" alt="aws powered" /> <img src="https://img.shields.io/badge/MCP-Compatible-purple?style=for-the-badge" alt="mcp compatible" /> ### 🚀 **Making Earth Observation as Easy as Having a Conversation** **From PhD-level complexity to natural language queries in one install** *"Show me crop health in Iowa"* • *"Analyze vegetation in California"* • *"Track water levels in Lake Tahoe"* [🎯 The Revolution](#-the-geospatial-ai-revolution) • [⚡ Quick Start](#-hosted-version-2-minute-setup) • [🌟 What's Possible](#-what-becomes-possible) • [🛠️ Self-Host](#-self-hosting) </div> --- ## ⚡ Hosted Version (2-Minute Setup!) **Start using satellite imagery analysis immediately without any server setup!** ### 🚀 Quick Start #### Step 1: Get Your API Key **Try it now with this starter key:** ``` axion_6C1D_634DDAEAA324235F ``` **Need your own key?** Email **dhenenjay.2001@gmail.com** or [open an issue](https://github.com/Dhenenjay/Axion-MCP-SSE/issues/new?title=API%20Key%20Request&body=Please%20provide%20me%20an%20API%20key%20for%20Axion%20MCP) #### Step 2: Configure Claude Desktop Open your Claude Desktop config file: | OS | Config File Path | |----|------------------| | **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` | | **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` | | **Linux** | `~/.config/Claude/claude_desktop_config.json` | Add the following (replace `YOUR_API_KEY`): ```json { "mcpServers": { "axion": { "command": "npx", "args": ["-y", "axion-mcp", "--api-key", "YOUR_API_KEY"] } } } ``` #### Step 3: Restart Claude Desktop Done! Ask Claude: > *"Show me the NDVI vegetation map of Central Park, New York"* --- ### 💻 Alternative Installation Methods #### Using Environment Variables ```json { "mcpServers": { "axion": { "command": "npx", "args": ["-y", "axion-mcp"], "env": { "AXION_API_KEY": "your_key_here" } } } } ``` #### Global Install (if npx doesn't work) ```bash npm install -g axion-mcp ``` ```json { "mcpServers": { "axion": { "command": "axion-mcp", "args": ["--api-key", "YOUR_API_KEY"] } } } ``` #### Using sse-bridge.mjs Directly ```json { "mcpServers": { "axion": { "command": "node", "args": ["C:/path/to/sse-bridge.mjs", "https://axion-mcp-sse.onrender.com/sse", "YOUR_API_KEY"] } } } ``` --- ### ✨ Why Use the Hosted Version? - **🚀 2-minute setup** - Just add config and restart - **☁️ No server management** - Everything runs in the cloud - **🔒 Simple API key auth** - Secure and easy - **⚡ Always up-to-date** - Latest features automatically - **🌍 Free satellite data** - Access Sentinel-2, Landsat, NAIP - **💻 Zero maintenance** - No processes to manage - **🌐 Works anywhere** - No firewall issues, no ports to open ### 📦 Hosted Server Details - **NPM Package**: [axion-mcp](https://www.npmjs.com/package/axion-mcp) - **Server URL**: `https://axion-mcp-sse.onrender.com` - **Health Check**: [https://axion-mcp-sse.onrender.com/health](https://axion-mcp-sse.onrender.com/health) - **7 powerful tools** for satellite imagery analysis > 🌟 **Hosted Version Exclusive:** The hosted version includes **axion_sar2optical** - our proprietary **Axion Foundation Model** that converts SAR radar imagery to optical-like images, enabling cloud-free, day/night Earth observation. This AI-powered tool is only available through the hosted server. > **Note:** The hosted server runs on Render's free tier and may take 30 seconds to wake up if idle. For always-on access, consider [self-hosting](#-self-hosting). --- ## 🎯 The Geospatial AI Revolution **We are witnessing the "iPhone moment" for Earth observation.** Just like the iPhone made computing accessible to everyone, Axion Planetary MCP makes petabytes of satellite data accessible through simple conversation. ### 🔥 The Paradigm Shift **Before:** Building geospatial AI required PhD expertise, months of setup, complex APIs, and massive infrastructure. **Now:** Anyone can build sophisticated Earth observation AI agents with natural language and one command: `npm install` ``` Traditional Path: 1 Expert → 1 Year → 1 Specialized Tool Our Path: 1 Person → 2 Minutes → Unlimited Possibilities ``` ## 🌟 What Becomes Possible ### 👥 **Who Can Now Build Geospatial AI Agents:** | **Before Axion** ❌ | **After Axion** ✅ | |--------------------|-----------------| | PhD researchers with GIS expertise | **Farmers**: "Monitor my fields for crop health" | | Large corporations with dedicated teams | **City Planners**: "Track urban expansion patterns" | | Government agencies with massive budgets | **NGOs**: "Monitor deforestation in real-time" | | Tech giants with infrastructure | **Students**: "Study climate change impacts" | | | **Small Businesses**: "Analyze supply chain risks" | | | **Anyone**: Who can install npm and talk to AI | ### 🚀 **Real-World Transformations** #### **Precision Agriculture Revolution** 🌾 ``` Farmer: "Create an AI agent that monitors my 500-acre farm" Result: Daily crop health reports, irrigation optimization, vegetation stress detection, yield predictions ``` #### **Environmental Monitoring** 🌊 ``` Researcher: "Track water quality in Lake Tahoe" Result: Water index analysis, temporal changes, algae bloom detection, quality reports ``` #### **Urban Planning** 🏙️ ``` Planner: "Analyze urban heat islands in Phoenix" Result: Surface temperature maps, vegetation coverage, heat mitigation recommendations ``` --- ## 🛠️ Available Tools (6) ### axion_data Search satellite imagery from multiple collections: - **Sentinel-2** (10m resolution, 5-day revisit) - **Landsat 8/9** (30m resolution, 16-day revisit) - **NAIP** (1m aerial imagery, US only) ### axion_map Create interactive maps with: - Vegetation indices (NDVI, EVI, SAVI) - Water indices (NDWI, MNDWI) - Built-up index (NDBI) - True/false color composites - Custom band expressions ### axion_process Process imagery: - Cloud-free composites - Temporal mosaics - 9+ spectral indices - Band math expressions ### axion_classification ML land cover classification: - Random Forest classifier - Custom training points - Multi-class output - Accuracy metrics ### axion_export Export options: - GeoTIFF downloads - PNG thumbnails - Map tiles (XYZ) - Cloud storage (S3) ### axion_system System utilities: - Health check - Configuration info - Available collections --- ## 📚 Example Queries **Just talk to Claude like you would a geospatial expert:** ### 🌾 **Agriculture & Food Security** > *"Show me NDVI vegetation health for Iowa farmland"* > > *"Create a crop classification map for California's Central Valley"* > > *"Which areas show vegetation stress this month?"* ### 🌊 **Water Resources** > *"Calculate water index for Lake Mead"* > > *"Show me water bodies in the Nevada desert"* > > *"Track reservoir levels over time"* ### 🏢 **Urban Planning** > *"Map urban expansion in Austin, Texas"* > > *"Show built-up areas vs green spaces in Seattle"* > > *"Analyze land use changes in Denver"* ### 🌲 **Environmental Monitoring** > *"Monitor forest health in Yellowstone"* > > *"Create a false color composite of the Amazon"* > > *"Show vegetation changes between 2020 and 2024"* --- ## 🐳 Self-Hosting Want to run your own Axion MCP server? **No cloud credentials required** for basic functionality! ### Prerequisites - **Docker** (recommended) OR **Node.js 18+** - That's it! Satellite data comes from free public APIs. ### Option 1: Docker (Recommended) ```bash # Clone this repository git clone https://github.com/Dhenenjay/Axion-Planetary-MCP cd Axion-Planetary-MCP # Build the Docker image docker build -t axion-mcp . # Run without authentication (for local/personal use) docker run -p 3000:3000 -e REQUIRE_AUTH=false axion-mcp # OR run with authentication (for production/shared use) docker run -p 3000:3000 \ -e REQUIRE_AUTH=true \ -e AXION_API_KEY=your-secret-key-here \ axion-mcp # Test it's working curl http://localhost:3000/health # Should return: {"status":"healthy","tools":6} ``` ### Option 2: Run from Source ```bash # Clone and install git clone https://github.com/Dhenenjay/Axion-Planetary-MCP cd Axion-Planetary-MCP npm install # Build the SSE server npm run build:sse # Run (no auth) REQUIRE_AUTH=false npm run start:sse # OR with auth REQUIRE_AUTH=true AXION_API_KEY=your-key npm run start:sse ``` ### Connect Claude Desktop to Your Server **Without authentication:** ```json { "mcpServers": { "axion-local": { "command": "node", "args": ["C:/path/to/Axion-Planetary-MCP/sse-bridge.mjs", "http://localhost:3000/sse"] } } } ``` **With authentication:** ```json { "mcpServers": { "axion-local": { "command": "node", "args": ["C:/path/to/Axion-Planetary-MCP/sse-bridge.mjs", "http://localhost:3000/sse", "your-secret-key-here"] } } } ``` ### Cloud Deployment The included `Dockerfile` works with any container platform: | Platform | How to Deploy | |----------|---------------| | **Render** | Fork repo → New Web Service → Connect GitHub → Deploy | | **Railway** | `railway init` → `railway up` | | **Fly.io** | `flyctl launch` → `flyctl deploy` | | **AWS ECS** | Push to ECR → Create task definition → Run service | | **Google Cloud Run** | `gcloud run deploy` | ### Environment Variables Reference | Variable | Required | Description | |----------|----------|-------------| | `PORT` | No | Server port (default: 3000) | | `REQUIRE_AUTH` | No | Enable API key auth (default: true) | | `AXION_API_KEY` | If auth enabled | Your API key for authentication | | `AWS_ACCESS_KEY_ID` | No | For S3 exports only | | `AWS_SECRET_ACCESS_KEY` | No | For S3 exports only | | `AWS_REGION` | No | AWS region (default: us-east-1) | | `AXION_S3_EXPORTS_BUCKET` | No | S3 bucket for GeoTIFF exports | ### What You Get Without Any Credentials ✅ **Full satellite data search** (Sentinel-2, Landsat, NAIP) ✅ **Interactive map generation** (NDVI, NDWI, false color, etc.) ✅ **Image processing** (composites, indices, band math) ✅ **ML classification** (Random Forest land cover) ✅ **System health & info** ### What Requires AWS Credentials (Optional) ⚠️ **GeoTIFF exports to S3** - requires AWS credentials and S3 bucket ⚠️ **Large file downloads** - exports over 10MB need S3 ### Docker Compose Example ```yaml version: '3.8' services: axion: build: . ports: - "3000:3000" environment: - NODE_ENV=production - REQUIRE_AUTH=true - AXION_API_KEY=${AXION_API_KEY} # Set in .env file # Optional AWS for exports: # - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} # - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} restart: unless-stopped ``` --- ## 📡 Data Sources | Collection | Resolution | Coverage | Revisit | |------------|-----------|----------|---------| | Sentinel-2 L2A | 10-60m | Global | 5 days | | Landsat C2 L2 | 30m | Global | 16 days | | NAIP | 0.6-1m | USA | 2-3 years | All data accessed via [AWS Earth Search STAC API](https://earth-search.aws.element84.com/v1) (free, no auth required). --- ## 🔧 Troubleshooting ### "Command not found: npx" Install Node.js 18+ from [nodejs.org](https://nodejs.org) ### "Unauthorized - Invalid API key" 1. Verify your API key is correct 2. Make sure there are no extra spaces 3. Try with environment variable: `"env": { "AXION_API_KEY": "your_key" }` ### "Connection refused" The hosted server may be sleeping (free tier). Wait 30 seconds and try again, or self-host. ### Claude doesn't show Axion tools 1. Completely quit Claude Desktop 2. Check config JSON syntax at [jsonlint.com](https://jsonlint.com) 3. Restart Claude Desktop 4. Look for "axion" in Claude's tool list --- ## 🏗️ Architecture ``` ┌─────────────────┐ │ Claude AI │ (Your AI Assistant) └────────┬────────┘ │ MCP Protocol ▼ ┌─────────────────┐ │ axion-mcp │ (NPM Bridge Package) └────────┬────────┘ │ SSE/HTTP ▼ ┌─────────────────┐ │ Axion Server │ (Cloud or Self-hosted) └────────┬────────┘ │ STAC API ▼ ┌─────────────────┐ │ AWS Earth │ (Free Satellite Data) │ Search │ Sentinel-2, Landsat, NAIP └─────────────────┘ ``` --- ## 🤝 Contributing Contributions welcome! Please feel free to: - Report bugs via [GitHub Issues](https://github.com/Dhenenjay/Axion-Planetary-MCP/issues) - Submit pull requests - Suggest new features - Improve documentation --- ## 📄 License MIT License - feel free to use in your projects! --- ## 💬 Support - **GitHub Issues**: [Report bugs or request features](https://github.com/Dhenenjay/Axion-Planetary-MCP/issues) - **Hosted Server**: [axion-mcp-sse.onrender.com](https://axion-mcp-sse.onrender.com) - **NPM Package**: [axion-mcp](https://www.npmjs.com/package/axion-mcp) --- <div align="center"> ## 🎆 **The Future is Now** **This isn't just a tool—it's the foundation of a revolution.** We're democratizing Earth observation, making geospatial intelligence as accessible as sending a text message. ### 🌍 What Will You Build? 🌾 **Agricultural AI that monitors crops?** • 🌊 **Water analysis that tracks resources?** • 🌳 **Forest monitoring that fights climate change?** --- **The Earth is waiting. The tools are ready. The only question is: what will you discover?** *From PhD-level complexity to conversational simplicity in one command* ✨ **Built with ❤️ to accelerate humanity's response to our biggest challenges** </div>