{"id":26570917,"url":"https://github.com/webcoderz/MCP-Geo","last_synced_at":"2025-03-22T22:19:47.192Z","repository":{"id":269352549,"uuid":"907138746","full_name":"webcoderz/MCP-Geo","owner":"webcoderz","description":"Geocoding MCP server with GeoPY!","archived":false,"fork":false,"pushed_at":"2025-01-21T01:42:33.000Z","size":48,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-07T10:51:34.684Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webcoderz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-22T23:03:19.000Z","updated_at":"2025-02-18T19:45:07.000Z","dependencies_parsed_at":"2024-12-23T00:28:44.326Z","dependency_job_id":"4845ab82-5172-49dc-99cd-546d4e39f53b","html_url":"https://github.com/webcoderz/MCP-Geo","commit_stats":null,"previous_names":["webcoderz/mcp-geo"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcoderz%2FMCP-Geo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcoderz%2FMCP-Geo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcoderz%2FMCP-Geo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webcoderz%2FMCP-Geo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webcoderz","download_url":"https://codeload.github.com/webcoderz/MCP-Geo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245026689,"owners_count":20549188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-22T22:19:21.970Z","updated_at":"2025-03-22T22:19:47.178Z","avatar_url":"https://github.com/webcoderz.png","language":"Python","readme":"# MCP-Geo\nGeocoding MCP server with GeoPY!\n\n\n\u003ca href=\"https://glama.ai/mcp/servers/ujss4qy5fs\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/ujss4qy5fs/badge?v=1\" /\u003e\n\u003c/a\u003e\n\n## 📋 System Requirements\n\n\n- Python 3.6+\n\n## 📦 Dependencies\n\nInstall all required dependencies:\n\n```bash\n# Using uv\nuv sync\n```\n\n### Required Packages\n- **fastmcp**: Framework for building Model Context Protocol servers\n- **geoPy**: Python library for accessing and geocoding/reverse geocoding locations.\n\n\nAll dependencies are specified in `requirements.txt` for easy installation.\n\n## 📑 Table of Contents\n- [System Requirements](#-system-requirements)\n- [Dependencies](#-dependencies)\n- [MCP Tools](#%EF%B8%8F-mcp-tools)\n- [Getting Started](#-getting-started)\n- [Installation Options](#-installation-options)\n  - [Claude Desktop](#option-1-install-for-claude-desktop)\n  - [Elsewhere](#option-2-install-elsewhere)\n- [Safety Features](#-safety-features)\n- [Development Documentation](#-development-documentation)\n- [Environment Variables](#%EF%B8%8F-environment-variables)\n\n## 🛠️ MCP Tools\n\nThis MCP server provides the following geocoding tools to Large Language Models (LLMs):\n\n### geocode_location\n\n- Takes a user-provided address or place name and returns the best match’s latitude, longitude, and formatted address.\n\n- Handles errors gracefully and returns None if the location is not found or if an error occurs.\n\n### reverse_geocode\n\n- Takes a latitude and longitude and returns the nearest address.\n- Useful for finding descriptive information about a point on the map.\n\n### geocode_with_details\n\n- Similar to geocode_location but returns additional data such as bounding boxes and more detailed address info, if supported by the geocoder.\n\n### geocode_multiple_locations\n\n- Accepts a list of address strings and returns a list of geocoding results (lat/lon/address) for each address.\n- Rate-limited to avoid hitting geocoding service quotas.\n\n### reverse_geocode_multiple_locations\n\n- Accepts a list of [lat, lon] pairs to perform reverse geocoding for each.\n- Returns a list of dictionaries containing lat, lon, and address or None for unsuccessful lookups, also rate-limited.\n\n### distance_between_addresses\n\n- Calculate the distance between two addresses or place names.\n- accepts 2 addresses and a unit of measurement (miles/kilometer)\n- Returns the distance in the specified unit, or None if either address could not be geocoded.\n\n### distance_between_coords\n\n- Calculate the distance between two lat/lon pairs.\n- accepts 2 pairs of latitude and longitude and a unit of measurement (kilometer/miles)\n- Returns the distance in the specified unit.\n\n\n## 🚀 Getting Started\n\nClone the repository:\n\n```bash\ngit clone https://github.com/webcoderz/MCP-Geo.git\ncd MCP-Geo\n```\n\n\n## 📦 Installation Options\n\nYou can install this MCP server in either Claude Desktop or elsewhere. Choose the option that best suits your needs.\n\n### Option 1: Install for Claude Desktop\n\nInstall using FastMCP:\n\n```bash\nfastmcp install geo.py --name \"MCP Geo\"\n```\n\n### Option 2: Install elsewhere\n\nTo use this server anywhere else:\n\n\n1. Add the following configuration to the settings file:\n\n```json\n{\n    \"mcp-geo\": {\n        \"command\": \"uv\",\n        \"args\": [\n          \"--directory\",\n          \"MCP-Geo\",\n          \"run\",\n          \"geo.py\"\n        ],\n        \"env\": {\n        \"NOMINATIM_URL\": \"${NOMINATIM_URL}\",\n        \"SCHEME\": \"http\",\n        \"GEOCODER_PROVIDER\": \"nominatim\"\n        }\n    }\n}\n```\n\n\n🔒 Safety Features\n\t•\tRate Limiting: Each geocoding call is rate-limited (e.g., 1-second delay) to avoid excessive requests that violate usage limits.\n\t•\tError Handling: Catches geopy exceptions (timeouts, service errors) and returns safe None results instead of crashing.\n\n📚 Development Documentation\n\nIf you’d like to extend or modify this server:\n\t•\tCheck geo.py for how each tool is implemented and how geopy is integrated.\n\t•\tAdjust environment variables to switch providers (Nominatim, ArcGIS, Bing, etc.).\n\t•\tLook at geopy’s official docs for advanced usage like bounding boxes, language settings, or advanced data extraction.\n\n⚙️ Environment Variables\n\nConfigure the server using environment variables:\n\n| Variable             | Description                              | Default            |\n |----------------------|------------------------------------------|--------------------|\n| `GEOCODER_PROVIDER` (optional)   | \"nominatim\", \"arcgis\", or \"bing\"     | nominatim          |\n| `NOMINATIM_URL` (optional)       | Domain for Nominatim | nominatim.openstreetmap.org       |\n| `SCHEME` (optional)              | http/https    | http               |\n| `ARC_USERNAME` (optional for ArcGIS)        | ArcGIS username            | None               |\n| `ARC_PASSWORD` (optional for ArcGIS)        | ArcGIS password      | None               |\n| `BING_API_KEY` (required for Bing)        | Your Bing Maps key.      | None               |\n\nThese can be set in your shell or in the MCP settings file for your environment. If more are needed just edit geo.py and add them in to whichever geocoder you are using.\n","funding_links":[],"categories":["Location \u0026 Maps","Data Access \u0026 Integration Mcp Servers","MCP 服务器精选列表","🤖 AI/ML","Legend","پیاده‌سازی‌های سرور","Table of Contents","Uncategorized"],"sub_categories":["GIS","🌍 地理位置与出行","🗺️ \u003ca name=\"location-services\"\u003e\u003c/a\u003eLocation Services","🗺️ \u003ca name=\"location-services\"\u003e\u003c/a\u003eخدمات مکانی","Location Services","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebcoderz%2FMCP-Geo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebcoderz%2FMCP-Geo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebcoderz%2FMCP-Geo/lists"}