@shyzus/mcp-geocrafter

v1.0.5

Published

20 days ago

GeoCrafter - MCP server for geocoding and reverse geocoding - Powered by Nominatim API

0High
0Medium
0Low

shyzus

mcp geocoding nominatim location address gps chatgpt

🗺️ GeoCrafter - Geocoding Server for ChatGPT

GeoCrafter is a clean, modular MCP server for geocoding and reverse geocoding - Powered by Nominatim API (OpenStreetMap).

⚠️ Disclaimer

This project is independent and unofficial.

❌ Not affiliated with OpenStreetMap or Nominatim
❌ Not sponsored by these organizations
✅ Uses public data from the Nominatim API
✅ Educational and practical purpose project

Geocoding data comes from the Nominatim API, which uses OpenStreetMap data.

🎯 What is it?

This application allows ChatGPT and other MCP clients to access geocoding services with a clean, modular architecture that serves as a template for future MCP servers.

✨ Features

🔍 Address to GPS - Convert addresses to coordinates
📍 GPS to Address - Convert coordinates to addresses
🏗️ Modular Architecture - Clean separation of concerns, reusable for future MCP servers
🔌 Dual Mode - Works with ChatGPT (HTTP) and IDEs (stdio)
🗺️ GeoJSON Map Viewer - Render interactive maps inside ChatGPT with fullscreen controls (Apps SDK)

💬 Usage example

In ChatGPT, simply ask:

"What are the coordinates of the Eiffel Tower?"

Or:

"What is the address at coordinates 48.8566, 2.3522?"

ChatGPT will use the MCP server to get the information.

🏗️ Architecture: ChatGPT MCP App

What is a ChatGPT App?

ChatGPT Apps (via Apps SDK) allow you to extend ChatGPT with:

Custom tools (call external APIs)
Real-time data (up-to-date information)

How does it work?

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│   ChatGPT   │ ◄─────► │  MCP Server  │ ◄─────► │  Nominatim   │
│             │  HTTP   │  (Node.js)   │  HTTP   │  API         │
└─────────────┘         └──────────────┘         └──────────────┘

ChatGPT calls your MCP server via the Model Context Protocol
The MCP server fetches data from the Nominatim API
The results are returned to ChatGPT

MCP Protocol

MCP (Model Context Protocol) is an open standard created by Anthropic that allows LLMs to access external data and tools securely. It is used by:

ChatGPT (via Apps SDK)
Claude Desktop
Cursor
Other MCP clients

🚀 Quick Start

Use with Cursor / Claude Desktop / Warp

The easiest way - Install the npm client that connects to the remote server:

{
  "mcpServers": {
    "mcp-geocrafter": {
      "command": "npx",
      "args": ["-y", "@shyzus/mcp-geocrafter"]
    }
  }
}

Config file locations:

Cursor: ~/.cursor/mcp.json (macOS/Linux) or %APPDATA%\Cursor\mcp.json (Windows)
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Warp: In Warp AI settings

Use with ChatGPT

A production server is available and ready to use!

Server URL: https://geocrafter.rankorr.red/mcp

ChatGPT Configuration

Have a ChatGPT account with subscription (ChatGPT Plus, Team, or Enterprise)
Open ChatGPT in your browser → Go to Settings (⚙️)
Go to "Apps & Connectors"
Enable developer mode:
- In "Advanced Settings", enable developer mode
- Go back
Create a new application:
- The "Create" button now appears in the top right
- Click on it
- Fill in the form:
  - Name: "GeoCrafter" (or another name)
  - Image: Add an icon/image (optional)
  - Server URL: https://geocrafter.rankorr.red/mcp
  - Authentication: Select "None"
- Click "Create"
The application is now available in ChatGPT and will activate automatically when you ask ChatGPT to use it

Test it!

Ask a question in ChatGPT:

"What are the coordinates of Paris, France?"

Or to test directly:

"Use GeoCrafter to find the address at coordinates 48.8566, 2.3522"

For developers - Local installation

# 1. Clone the project
git clone https://github.com/rankorr/mcp-location.git
cd mcp-location

# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Use locally
npx @modelcontextprotocol/inspector node dist/index.js

📱 Deployment and Development

🔒 CI/CD secrets configuration: To automatically deploy to a VPS with GitHub Actions and Portainer, see SECRETS.md for GitHub secrets configuration.

💡 To use the application in ChatGPT, see the 🚀 Quick Start section above for complete instructions.

Option 1: Local Testing with ngrok (For development)

1. Start the HTTP server

npm run start:http

The server starts on http://localhost:3000

2. Expose with ngrok

In a new terminal:

# Install ngrok if necessary
brew install ngrok  # macOS
# or download from https://ngrok.com/download

# Expose port 3000
ngrok http 3000

You get a public URL like:

https://abc123.ngrok-free.dev

Important:

Note the complete URL: https://abc123.ngrok-free.dev/mcp (or just https://abc123.ngrok-free.dev/ - both work)
The server uses Streamable HTTP transport (modern MCP standard, replaces deprecated SSE)

3. Configure the application in ChatGPT

Follow the configuration instructions in the 🚀 Quick Start section, using your ngrok URL (https://your-url.ngrok-free.dev/mcp) instead of the production URL.

Option 2: Deploy your own server (For developers)

Note: If you just want to use the application, see the 🚀 Quick Start section which uses the production server already available.

This project includes a GitHub Actions workflow that automatically deploys to a VPS with Docker and Portainer.

VPS Deployment with GitHub Actions

Configure GitHub secrets according to SECRETS.md
Push to the main branch
GitHub Actions will automatically:
- ✅ Test TypeScript code
- ✅ Deploy to your VPS via Portainer
- ✅ Publish to npm (if version not already published)
- ✅ Check health status

Version Management & Git Tags

⚠️ IMPORTANT : Avant chaque publication npm, créer un tag Git !

Format des tags : {MAJOR}.{MINOR}.{PATCH} (sans préfixe "v")

Exemples : 1.0.0, 1.0.1, 1.1.0, 2.0.0

Processus de release :

Incrémenter la version dans package.json :

npm version patch   # 1.0.0 → 1.0.1
npm version minor   # 1.0.0 → 1.1.0
npm version major   # 1.0.0 → 2.0.0

Créer le tag Git correspondant :

VERSION=$(node -p "require('./package.json').version")
git tag -a "$VERSION" -m "Release $VERSION - {description}"

Commit et push (y compris les tags) :

git add package.json
git commit -m "chore: bump version to $VERSION"
git push origin main
git push origin --tags

Le workflow GitHub Actions publiera automatiquement sur npm si la version n'existe pas déjà.

Branches :

main : Production (protégée, déploiement automatique)
develop : Développement (branche de travail principale)

Voir CONTEXT.md pour plus de détails sur le workflow de développement.

Benefits:

Automatic deployment on each push
Free SSL with Traefik + Let's Encrypt
Integrated health monitoring
Centralized logs

Other cloud platforms

You can also deploy on:

Railway - Automatic deployment from GitHub
Render - Managed service with free SSL
Fly.io - Edge computing with global deployment
Google Cloud Run - Serverless with automatic scaling

See the Apps SDK deployment guide for more details.

Configure your server in ChatGPT

Once deployed:

Note your server URL: https://your-domain.com/mcp (or / - both endpoints work)
The server uses Streamable HTTP transport (modern MCP standard)
Follow the instructions in 🚀 Quick Start

🧪 Local Testing (without ChatGPT)

With Cursor (the IDE you're using)

The MCP server already works in Cursor! Ask me a question about locations and I'll use the server.

With Claude Desktop

Install Claude Desktop
Configure in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-geocrafter": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-location/dist/index.js"
      ]
    }
  }
}

Restart Claude Desktop
The MCP icon 🔌 appears in the bottom left

With the MCP inspector

npx @modelcontextprotocol/inspector node dist/index.js

Opens a web interface to test all tools.

🗺️ GeoJSON Map Viewer (ChatGPT UI Tool)

display_geojson_map is a ChatGPT-only tool that returns an interactive Leaflet map embedded inside the conversation. It leverages the OpenAI Apps SDK widget runtime (text/html+skybridge) and ships with a dedicated template bundled in this repository.

Inputs

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | geojson | object | string | ✅ | GeoJSON FeatureCollection to render. Accepts either a parsed object (recommended) or a JSON string for compatibility with ChatGPT prompts. | | title | string | ❌ | Custom title displayed above the map. Defaults to Carte GeoJSON. | | description | string | ❌ | Caption shown next to the title (e.g., context or instructions). | | highlightColor | string | ❌ | Hex color (e.g., #2563eb) applied to outlines, fills and markers. |

Output

Inline widget rendered directly in ChatGPT with:
- OpenStreetMap tiles + Leaflet overlay
- Computed bounding box & auto-fit
- Recentrer button
- Agrandir button (toggles fullscreen inside ChatGPT, matching the requirement “option de l’ouvrir en grand”)
Lightweight structuredContent summary exposed to the model (feature count, geometry types, bounds)
Full GeoJSON stays inside _meta, so it is only consumed by the widget (keeps the model prompt small)

Example call

{
  "name": "display_geojson_map",
  "arguments": {
    "title": "Stations autour de Lyon",
    "description": "Résultats de places_nearby sur 5 km",
    "geojson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": { "type": "Point", "coordinates": [4.8357, 45.7640] },
          "properties": { "label": "Lyon Part-Dieu" }
        }
      ]
    }
  }
}

ℹ️ The stdio server (Cursor/Claude Desktop) ignores this tool, which is fine: it is explicitly designed for ChatGPT with UI widgets.

📂 Project Structure

mcp-location/
├── src/
│   ├── config.ts              # Configuration centralisée
│   ├── types.ts               # Types TypeScript partagés
│   ├── client/
│   │   └── nominatimClient.ts # Client API Nominatim
│   ├── tools/
│   │   ├── searchAddress.ts   # Tool: adresse → GPS
│   │   ├── reverseGeocode.ts  # Tool: GPS → adresse
│   │   └── displayGeoJsonMap.ts # Tool: GeoJSON → widget UI
│   ├── resources/
│   │   └── mapViewerTemplate.ts # Template HTML (text/html+skybridge) pour ChatGPT
│   ├── servers/
│   │   ├── stdio.ts           # Serveur stdio (IDEs)
│   │   └── http.ts             # Serveur Streamable HTTP (ChatGPT)
│   ├── utils/
│   │   └── errors.ts           # Gestion erreurs centralisée
│   ├── index.ts                # Entry point stdio
│   ├── http-server.ts          # Entry point HTTP
│   └── http-client.ts          # Client npm
├── dist/                       # Compiled code (generated)
├── Dockerfile                  # Multi-stage Docker image
├── docker-compose.yml          # Stack with Traefik labels
├── .github/workflows/deploy.yml # CI/CD pipeline
├── package.json                # Server dependencies
├── tsconfig.json               # TypeScript config
└── README.md                   # This file

🛠️ Available Commands

📖 Full documentation: COMMANDS.md

Quick Reference

# 🌟 Recommended for ChatGPT development (2 terminals)
npm run tunnel           # Terminal 1: ngrok (keep running)
npm run dev              # Terminal 2: Dev server with hot-reload

# Alternative: All-in-one
npm run dev:tunnel       # Dev + ngrok in parallel

# Testing
npm run inspect          # Launch MCP Inspector
npm run health           # Health check

# Build & Production
npm run build            # Compile TypeScript
npm run rebuild          # Clean + Build
npm run build:start      # Build then start

# Utilities
npm run kill             # Kill process on port 3000
npm run kill:tunnel      # Kill ngrok

Cursor Commands

Available via Cmd+Shift+P:

dev-server - Dev with hot-reload (recommended)
tunnel-only - Launch ngrok (keep running)
mcp-inspector - Launch MCP Inspector
build / rebuild / clean
kill-server / kill-tunnel

See COMMANDS.md for the complete list.

🔧 Advanced Configuration

Environment variables

Create a .env file:

PORT=3000                          # HTTP server port
NODE_ENV=production                # Environment
NOMINATIM_BASE_URL=https://nominatim.openstreetmap.org  # Optional
NOMINATIM_USER_AGENT=MyApp/1.0    # Optional (recommended by Nominatim)
CORS_ORIGIN=*                      # CORS origin (default: * in dev, https://chatgpt.com in prod)

Customize the Nominatim API

The Nominatim API is public but you can:

Use a custom instance (set NOMINATIM_BASE_URL)
Set a custom User-Agent (recommended, set NOMINATIM_USER_AGENT)

🏗️ Architecture Details

This project serves as a template/base for future MCP servers with a clean, modular architecture:

Separation of Concerns

config.ts: Environment variables, constants, validation
types.ts: Shared TypeScript interfaces
client/: External API abstraction (Nominatim)
tools/: Business logic (validation, transformation, formatting)
servers/: MCP implementation (stdio/Streamable HTTP), reuses tools
utils/errors.ts: Custom error classes, formatting

See CONTEXT.md for detailed architecture documentation.

📚 Resources & Documentation

Project Documentation

CONTEXT.md - Project memory (status, decisions, changelog)
COMMANDS.md - All npm scripts and Cursor commands
OPENAI_APPS_SDK_REFERENCE.md - Complete SDK reference guide

Official documentation

OpenAI Apps SDK - Complete ChatGPT Apps guide
Apps SDK - MCP Server - Server config
Model Context Protocol - MCP spec
MCP SDK TypeScript - Node.js SDK
Nominatim API - Geocoding API docs

Community

MCP Servers Repository - Official examples
OpenAI Apps Examples - App examples

🐛 Debugging & Troubleshooting

Server won't start

# Check that Node.js is installed
node --version  # Must be 18+

# Check that dependencies are installed
npm install

# Full rebuild
npm run build

UI doesn't display in ChatGPT

Check ngrok logs - See if ChatGPT is making requests
Check the server - http://localhost:3000/health must respond
Refresh the connector in ChatGPT (Settings → Apps → Refresh)
Check the CORS - Allowed domains in src/servers/http.ts

CORS errors

The server allows all origins in dev. In production, restrict in src/servers/http.ts:

res.setHeader('Access-Control-Allow-Origin', 'https://chatgpt.com');

Logs

Server logs display in the terminal. For more details:

console.log('MCP Request:', jsonRpcRequest.method);

🚀 Use This Project as a Template

This project is a complete template for creating your own ChatGPT apps with a clean architecture.

To create your own app:

Duplicate this project
Replace the Nominatim API with your API
Modify the tools in src/tools/
Customize the configuration in src/config.ts
Deploy!

Possible app examples

🎬 Cinema - Movie search and showtimes
🍽️ Restaurants - Reservations with menu
🏨 Hotels - Search and availability
📦 Delivery - Package tracking
📰 News - Articles with integrated reader
🎵 Music - Audio player in ChatGPT
📊 Analytics - Charts and dashboards

The possibilities are endless! 🚀

📝 License

MIT - Use freely for your personal or commercial projects.

🙏 Credits & Attributions

Geocoding Data - Nominatim API - OpenStreetMap data
MCP Protocol - Anthropic
Apps SDK - OpenAI

Data & Licenses

Geocoding data comes from the Nominatim API which uses OpenStreetMap data. This data is provided under the Open Database License (ODbL).

📞 Support

For any questions:

📖 Check the Apps SDK documentation
💬 Open an issue on GitHub
📧 Contact the team

Have fun with your ChatGPT app! 📍✨