Amapmcp

🚀 Gaode Map Navigation MCP Tool

This is a Gaode Map Navigation MCP (Model Context Protocol) tool based on FastAPI and fastmcp. It provides an interactive map page, supporting three navigation types: driving, cycling, and walking. Real-time route planning can be achieved by sending navigation commands through the MCP interface. The system uses WebSocket for real-time communication and session management based on sessionid to ensure the security and independence of multi-user usage.

🚀 Quick Start

1. Environment Setup

We use uv for Python environment management. First, make sure uv is installed:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new virtual environment
uv venv

# Activate the virtual environment
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

2. Install Dependencies

# Install dependencies using uv
uv pip install -r requirements.txt

# Synchronize dependencies (recommended)
uv sync

3. Set Environment Variables (Optional)

If you have your own Gaode Map API key, you can set the environment variables:

# Set environment variables
export AMAP_API_KEY="Your Gaode Map API Key"
export AMAP_SECURITY_CODE="Your Gaode Map Security Key"

4. Start the Server

# Run directly
python main.py

# Or use uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000

After the server starts, you will see the following information:

🚀 Starting the Gaode Map Navigation MCP Server...
🔧 MCP Endpoint: http://localhost:8000/mcp
📚 API Documentation: http://localhost:8000/docs

Usage Instructions:
1. Create a session using the MCP tool 'create_session'.
2. Access the map page using the returned sessionid.
3. Send navigation commands using the MCP tool 'send_navigation_to_map'.

✨ Features

• WebSocket Real-time Communication: The map page receives navigation commands in real-time via WebSocket.
• Session Isolation: Each user has an independent map session and connection.
• Multiple Navigation Types: Supports driving, cycling, and walking navigation.
• Mixed Input: Supports a combination of latitude/longitude coordinates and keyword locations.
• Automatic Reconnection: Automatically reconnects when the WebSocket connection is disconnected.
• Secure Access: Access control based on sessionid.
• Environment Variable Support: Allows setting custom API keys through environment variables.
• URL Parameter Passing: Keys are dynamically passed through URL parameters for flexibility and security.
• Responsive Design: Adapts to various screen sizes.

📦 Installation

Environment Setup

We use uv for Python environment management. Ensure uv is installed:

# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new virtual environment
uv venv

# Activate the virtual environment
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

Install Dependencies

# Install dependencies
uv pip install -r requirements.txt

# Synchronize dependencies (recommended)
uv sync

Set Environment Variables (Optional)

export AMAP_API_KEY="Your Gaode Map API Key"
export AMAP_SECURITY_CODE="Your Gaode Map Security Key"

Start the Server

# Run directly
python main.py

# Or use uvicorn
uvicorn main:app --host 0.0.0.0 --port 8000

💻 Usage Examples

Basic Usage

1. Set Environment Variables → (Optional) Set AMAP_API_KEY and AMAP_SECURITY_CODE.
2. Start the Service → Run python main.py.
3. Create a Session → Use the MCP tool create_session.
4. Access the Map → Use the returned full link (including key parameters) to access the map page.
5. Send Navigation Commands → Use the MCP tool send_navigation_to_map.
6. View Results → The map displays the navigation route in real-time via WebSocket.

📚 Documentation

Architecture Design

• Session Management: A multi-user session isolation system based on sessionid.
• Map Page: An interactive HTML page provided by FastAPI, requiring a valid sessionid to access.
• WebSocket Communication: Real-time two-way communication, supporting instant push of navigation commands.
• MCP Tools: create_session to create a session, send_navigation_to_map to send navigation commands.
• Multiple Navigation Types: Supports driving, cycling, and walking navigation modes.
• Mixed Input: Supports a combination of latitude/longitude coordinates and keyword locations.

API Interfaces

Main Endpoints

Check System Status

# View all sessions
curl "http://localhost:8000/sessions"

# View the command queue status
curl "http://localhost:8000/queue-status"

# Health check
curl "http://localhost:8000/health"

Get Gaode Map API Key

1. Visit Gaode Open Platform.
2. Register an account and log in.
3. Create an application and obtain the API Key.
4. Enable the JavaScript API in the Web service.

🔧 Technical Details

Technology Stack

• FastAPI: A modern, fast Web framework supporting WebSocket.
• fastmcp: Implementation of MCP (Model Context Protocol).
• uvicorn: ASGI server.
• WebSocket: Real-time two-way communication protocol.
• Gaode Map JavaScript API: Map, driving, cycling, and walking navigation services.

📄 License

This project is under the MIT License.

Disclaimer: This project is for learning and technical research purposes only. Users should:

• Comply with the Gaode Map API usage terms.
• Not use this project in a commercial production environment.
• Assume the security risks such as API key leakage on their own.
• Ensure compliance with local laws and regulations.

The author is not responsible for any direct or indirect losses caused by the use of this project.

⚠️ Important Note

⚠️ Important Note

This service is only for learning and development testing purposes. It is strictly prohibited to use it in a production environment!

• 🔒 API Key Exposure Risk: The Gaode Map API key is passed through URL parameters, posing a risk of exposure.
• 🌐 Public Network Access Danger: Without key encryption and access control, it should not be deployed to the public network.
• 📊 Log Leakage Risk: The key may be recorded in the server access logs.
• 🔐 Lack of Security Protection: It lacks security measures such as HTTPS, key encryption, and access restrictions.

💡 Usage Tip

• ✅ Only use it in a local development environment.
• ✅ Use a test API key.
• ✅ Ensure that the firewall blocks external access.
• ❌ Do not use a production environment key.
• ❌ Do not deploy it to a public network server.

📂 Project Structure

08.amap/
├── main.py                 # Main program file
├── main.js                 # Client-side JavaScript file
├── main.html               # Map page HTML file
├── pyproject.toml          # Project configuration file
├── README.md               # Project documentation (Chinese)
├── README_EN.md            # Project documentation (English)
├── README_JA.md            # Project documentation (Japanese)
└── uv.lock                 # Dependency lock file

⚠️ Precautions

1. 🔐 Security First: This service is only for learning and testing. Do not use it in a production environment!
2. 🔑 Key Security: The API key is passed through URL parameters, with a risk of leakage. Use it only locally.
3. 🌐 Network Requirement: A network connection is required to load map resources.
4. 🔒 Session Management: A session must be created before accessing the map page.
5. 💻 Browser Compatibility: It is recommended to use a modern browser (supporting WebSocket).
6. 📍 Coordinate System: The coordinate system used is WGS84.
7. 🚲 Navigation Limitation: The policy parameter is not supported for cycling and walking navigation.
8. 🔍 Search Requirement: City information must be provided when searching by keyword.
9. 📝 Log Risk: The key may be recorded in various levels of logs. Pay attention to cleaning.
10. 🔒 Access Control: Ensure that the service runs only in a trusted network.

🤝 Contribution

Welcome to submit Issues and Pull Requests!