Content
# Baidu Map MCP Server
## Overview
The Baidu Map API is now fully compatible with the [MCP Protocol](https://modelcontextprotocol.io/), making it the first map service provider in China to support the MCP protocol.
The MCP Server provided by Baidu Map includes 10 API interfaces that comply with the MCP protocol standards, covering reverse geocoding, place search, route planning, and more.
Developed using the `MCP Python SDK` and `MCP Typescript SDK`, any intelligent assistant that supports the MCP protocol (such as `Claude`, `Cursor`, and `Qianfan AppBuilder`, etc.) can be quickly integrated.
## Tools
1. Geocoding `map_geocode`
- Converts an address into corresponding location coordinates.
- Input: `address` address information
- Output: `location`
2. Reverse Geocoding `map_reverse_geocode`
- Converts coordinates into corresponding semantic addresses.
- Input: `location` latitude and longitude coordinates
- Output: `formatted_address`, `uid`, `addressComponent`
3. Place Search `map_search_places`
- Searches for places and POIs in various scenarios, including city search and circular area search.
- Input:
- `query` search keyword
- `location` center point for circular search
- `radius` radius for circular search
- `region` specified city for city search
- Output: List of POIs, including `name`, `location`, `address`, etc.
4. Place Details Retrieval `map_place_details`
- Retrieves detailed information about a POI based on its uid.
- Input: `uid`
- Output: POI details, including `name`, `location`, `address`, `brand`, `price`, etc.
5. Batch Route Calculation `map_distance_matrix`
- Calculates the route distance and travel time between all combinations of starting and ending points based on their coordinates.
- Input:
- `origins` list of starting latitude and longitude
- `destinations` list of ending latitude and longitude
- `mode` travel type, optional values include `driving`, `walking`, `riding`, default is `driving`
- Output: Time and distance for each route, including `distance`, `duration`, etc.
6. Route Planning `map_directions`
- Plans travel routes and time based on starting and ending coordinates, allowing specification of travel modes such as driving, walking, riding, and public transport.
- Input:
- `origin` starting latitude and longitude
- `destination` ending latitude and longitude
- `model` travel type, optional values include `driving`, `walking`, `riding`, `transit`, default is `driving`
- Output: Route details, including `steps`, `distance`, `duration`, etc.
7. Weather Query `map_weather`
- Queries weather based on administrative district code or latitude and longitude coordinates (to query weather using `location` latitude and longitude, the user must have **advanced permissions**).
- Input:
- `district_id` administrative district code
- `location` latitude and longitude coordinates
- Output: Weather information, including `temperature`, `weather`, `wind`, etc.
8. IP Location `map_ip_location`
- Obtains the current location based on the requested IP (localized to the city). If the requested parameter IP is IPv6, **advanced permissions** are required.
- Input: `ip` requested IP address
- Output: Current city and city center `location`
9. Real-time Traffic Query `map_road_traffic`
- Queries real-time traffic congestion conditions, allowing real-time traffic queries by specifying road names and area shapes (rectangle, polygon, circle).
- Input:
- `model` traffic query type (optional values include `road`, `bound`, `polygon`, `around`, default is `road`)
- `road_name` road name and direction, required when `model=road` (e.g., `Chaoyang Road South to North`)
- `city` city name or city adcode, required when `model=road` (e.g., `Beijing`)
- `bounds` latitude and longitude coordinates of the lower left and upper right corners of the area, required when `model=bound` (e.g., `39.912078,116.464303;39.918276,116.475442`)
- `vertexes` latitude and longitude coordinates of the vertices of the polygon area, required when `model=polygon` (e.g., `39.910528,116.472926;39.918276,116.475442;39.916671,116.459056;39.912078,116.464303`)
- `center` latitude and longitude coordinates of the center point of the circular area, required when `model=around` (e.g., `39.912078,116.464303`)
- `radius` radius of the circular area (meters), value range `[1,1000]`, required when `model=around` (e.g., `200`)
- Output: Traffic information, including `road_name`, `traffic_condition`, etc.
10. POI Intelligent Extraction `map_poi_extract`
- Requires **advanced permissions** to use, extracts POI-related information based on text content.
- Input: `text_content` text description for extracting POIs (complete travel routes, itinerary planning, scenic spot recommendation descriptions, etc., for example: "The Duku Highway and Tarim Lake in Xinjiang are beautiful, and the experience from Dushanzi Grand Canyon to Tianshan Mystery Grand Canyon is also great.")
- Output: Related POI information, including `name`, `location`, etc.
## Getting Started
Using the Baidu Map MCP Server can be done primarily in two ways: `Python` and `Typescript`, which are introduced below.
### Obtaining AK
Before choosing one of the two methods, you need to create a server-side AK in the [Baidu Map Open Platform](https://lbsyun.baidu.com/apiconsole/key) console. You need this AK to call the Baidu Map API capabilities.
### Python Integration
If you want to customize the capabilities of the Baidu Map MCP Server, you can integrate it through the [source code](./src/baidu-map/python/src/mcp_server_baidu_maps/map.py). For details, see the [Python integration documentation](./src/baidu-map/python/README.md).
In the v1.1 version update, we released the Baidu Map MCP Server via pypi: *mcp-server-baidu-maps*, which you can easily obtain and quickly configure using any Python package management tool.
#### Installation
##### Using uv (Recommended)
When using [`uv`](https://docs.astral.sh/uv/), no special installation is required. We will use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to run *mcp-server-baidu-maps* directly.
##### Using pip
Alternatively, you can install *mcp-server-baidu-maps* via pip:
```bash
pip install mcp-server-baidu-maps
```
After installation, you can run it as a script using the following command:
```bash
python -m mcp_server_baidu_maps
```
#### Configuration
Add the following configuration in any MCP client (such as Claude.app). Some clients may require some formatting adjustments.
The value corresponding to *BAIDU_MAPS_API_KEY* needs to be replaced with your own AK.
<details>
<summary>Using uvx</summary>
```json
"mcpServers": {
"baidu-maps": {
"command": "uvx",
"args": ["mcp-server-baidu-maps"],
"env": {
"BAIDU_MAPS_API_KEY": "<YOUR_API_KEY>"
}
}
}
```
</details>
<details>
<summary>Using pip installation</summary>
```json
"mcpServers": {
"baidu-maps": {
"command": "python",
"args": ["-m", "mcp_server_baidu_maps"],
"env": {
"BAIDU_MAPS_API_KEY": "<YOUR_API_KEY>"
}
}
}
```
</details>
After saving the configuration, restart your MCP client to use the Baidu Map MCP Server.
### Typescript Integration
#### Node.js Installation
For Typescript integration, you only need to install [node.js](https://nodejs.org/en/download).
When you can run
```bash
node -v
```
in the terminal, it indicates that your `node.js` has been successfully installed.
#### Configuration
Open the `Setting` in `Claude for Desktop`, switch to `Developer`, click `Edit Config`, and open the configuration file with any IDE.
Add the following configuration to the configuration file. BAIDU_MAP_API_KEY is the AK for accessing the Baidu Map Open Platform API, which can be obtained by applying on [this page](https://lbs.baidu.com/faq/search?id=299&title=677):
```json
{
"mcpServers": {
"baidu-map": {
"command": "npx",
"args": [
"-y",
"@baidumap/mcp-server-baidu-map"
],
"env": {
"BAIDU_MAP_API_KEY": "xxx"
}
}
}
}
```
Restart Claude, and the settings panel will have successfully loaded the Baidu Map MCP Server. You can see 8 available MCP tools in the software's main interface dialog, and click to view details.
#### Effect
You can now ask questions to verify the capabilities of the travel planning assistant.
### Integration via Qianfan AppBuilder Platform
For integration with the Qianfan platform, it currently supports SDK integration or API integration. You can build an application through AppBuilder, each application has a unique app_id, and then call the corresponding app_id in the Python file to use the Baidu Map Python MCP Tool.
Template code can be found below. By using the SDK Agent and the Map MCP Server, you can obtain navigation routes and route information, and provide travel suggestions.
#### Agent Configuration
Go to the [Qianfan platform](https://console.bce.baidu.com/ai_apaas/personalSpace/app), create a new application, and publish it.
Set the number of thoughts for the Agent to 6. Publish the application.
#### Calling
This code can serve as a template to call the already built and published App on the Qianfan platform in SDK form. Then download the MCP Server locally and write the relative path of the file into the code.
*** (Note: Use actual app_id, token, query, and mcp file) ***
```python
import os
import asyncio
import appbuilder
from appbuilder.core.console.appbuilder_client.async_event_handler import (
AsyncAppBuilderEventHandler,
)
from appbuilder.modelcontextprotocol.client import MCPClient
class MyEventHandler(AsyncAppBuilderEventHandler):
def __init__(self, mcp_client):
super().__init__()
self.mcp_client = mcp_client
def get_current_weather(self, location=None, unit="Celsius"):
return "{}'s temperature is {} {}".format(location, 20, unit)
async def interrupt(self, run_context, run_response):
thought = run_context.current_thought
# Green print
print("\033[1;31m", "-> Agent Intermediate Thought: ", thought, "\033[0m")
tool_output = []
for tool_call in run_context.current_tool_calls:
tool_res = ""
if tool_call.function.name == "get_current_weather":
tool_res = self.get_current_weather(**tool_call.function.arguments)
else:
print(
"\033[1;32m",
"MCP Tool Name: {}, MCP Parameters:{}\n".format(tool_call.function.name, tool_call.function.arguments),
"\033[0m",
)
mcp_server_result = await self.mcp_client.call_tool(
tool_call.function.name, tool_call.function.arguments
)
print("\033[1;33m", "MCP Result: {}\n\033[0m".format(mcp_server_result))
for i, content in enumerate(mcp_server_result.content):
if content.type == "text":
tool_res += mcp_server_result.content[i].text
tool_output.append(
{
"tool_call_id": tool_call.id,
"output": tool_res,
}
)
return tool_output
async def success(self, run_context, run_response):
print("\n\033[1;34m", "-> Agent Non-streaming Answer: ", run_response.answer, "\033[0m")
async def agent_run(client, mcp_client, query):
tools = mcp_client.tools
conversation_id = await client.create_conversation()
with await client.run_with_handler(
conversation_id=conversation_id,
query=query,
tools=tools,
event_handler=MyEventHandler(mcp_client),
) as run:
await run.until_done()
### User Token
os.environ["APPBUILDER_TOKEN"] = (
""
)
async def main():
appbuilder.logger.setLoglevel("DEBUG")
### Published Application ID
app_id = ""
appbuilder_client = appbuilder.AsyncAppBuilderClient(app_id)
mcp_client = MCPClient()
### Note that the path here is the relative path of the MCP Server file on the local machine
await mcp_client.connect_to_server("./<YOUR_FILE_PATH>/map.py")
print(mcp_client.tools)
await agent_run(
appbuilder_client,
mcp_client,
'Driving navigation from Beijing to Shanghai',
)
await appbuilder_client.http_client.session.close()
if __name__ == "__main__":
loop = asyncio.get_event_loop()
loop.run_until_complete(main())
```
#### Effect
Through the Agent's own reasoning, by calling multiple tools such as MCP Server place search, geocoding service, route planning service, etc., navigation routes and route information are obtained, along with travel suggestions.
Actual user request: ***“Please plan a one-day flower viewing tour in Beijing. Try to provide a more comfortable travel arrangement, and of course, pay attention to the weather conditions.”***
#### Thought Process
#### Agent Result
## Notes
In the Baidu Map MCP Server:
The incoming administrative district codes all use the [Baidu adcode mapping table](https://lbsyun.baidu.com/faq/api?title=webapi/download).
The incoming latitude and longitude coordinates all use the National Measurement Bureau's latitude and longitude coordinates `gcj02ll`. For details, see [Baidu Coordinate System](https://lbsyun.baidu.com/index.php?title=coordinate).
## License
[MIT](./LICENSE) © baidu-maps
## Authorization
Some advanced capabilities in the Baidu Map MCP Server require applying for **advanced permissions** to use. If needed, please [contact](https://lbsyun.baidu.com/apiconsole/fankui?typeOne=%E4%BA%A7%E5%93%81%E9%9C%80%E6%B1%82&typeTwo=%E9%AB%98%E7%BA%A7%E6%9C%8D%E5%8A%A1) us.
## Feedback
If you encounter any issues while using the Baidu Map MCP Server, please feel free to provide feedback through `issues` or the [Baidu Map Open Platform](https://lbsyun.baidu.com/apiconsole/fankui?typeOne=30046&typeTwo=53524&typeThree=1032776). We also welcome every positive `PR`. Thank you all for your support and contributions ❤️
## Updates
| Version | Feature Description | Update Date |
| ------- | ----------------------------------------- | ---------------- |
| V1.0 | Baidu Map MCP Server officially launched | 2025-03-21 |
| V1.1 | Added quick integration via `uvx` and `pip` | 2025-03-28 |
