Baidu Map

🚀 Baidu Maps MCP Server

Baidu Maps MCP Server provides a set of APIs compliant with the MCP protocol, enabling seamless integration with various intelligent agents for map-related services.

🚀 Quick Start

There are two main ways to use Baidu Maps MCP Server, namely through Python and Typescript, which are introduced below.

Obtain AK

Before choosing either method, you need to create a server-side AK in the console of the Baidu Maps Open Platform. Only with an AK can you call the Baidu Maps API.

Python Integration

If you wish to customize the capabilities of Baidu Maps MCP Server, you can integrate it via the source code. For detailed instructions, refer to the Python Integration Documentation.

In the v1.1 update, we released the Baidu Maps MCP Server mcp-server-baidu-maps on pypi. You can easily obtain and quickly configure it using any Python package management tool.

Installation

Using uv (Recommended)

When using uv, no special installation is required. We will use uvx to directly run mcp-server-baidu-maps.

Using pip

Alternatively, you can install mcp-server-baidu-maps via pip:

pip install mcp-server-baidu-maps

After installation, you can run it as a script using the following command:

python -m mcp_server_baidu_maps

Configuration

Add the following configuration to any MCP client (e.g., Claude.app). Some formatting adjustments may be required for certain clients.

Replace the value of BAIDU_MAPS_API_KEY with your own AK.

{
  "mcpServers": {
    "baidu-maps": {
      "command": "uvx",
      "args": ["mcp-server-baidu-maps"],
      "env": {
        "BAIDU_MAPS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

{
  "mcpServers": {
    "baidu-maps": {
      "command": "python",
      "args": ["-m", "mcp_server_baidu_maps"],
      "env": {
          "BAIDU_MAPS_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

After saving the configuration, restart your MCP client to use Baidu Maps MCP Server.

Typescript Integration

Node.js Installation

To integrate via Typescript, you only need to install node.js.

If you can run the following command in the terminal:

node -v

It indicates that node.js has been successfully installed.

Configuration

Open the Setting of Claude for Desktop, switch to Developer, click Edit Config, and open the configuration file with any IDE.

Add the following configuration to the file. BAIDU_MAP_API_KEY is the AK for accessing the Baidu Maps Open Platform API. Apply for it on this page:

{
    "mcpServers": {
        "baidu-map": {
            "command": "npx",
            "args": [
                "-y",
                "@baidumap/mcp-server-baidu-map"
            ],
            "env": {
                "BAIDU_MAP_API_KEY": "xxx"
            }
        }
    }
}

For Windows systems, additional configuration is required for JSON:

"mcpServers": {
 "baidu-map": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@baidumap/mcp-server-baidu-map"
      ],
      "env": {
        "BAIDU_MAP_API_KEY": "xxx"
      },
    }
}

Restart Claude. The Baidu Maps MCP Server should now be successfully loaded in the settings panel. You can see 8 available MCP tools in the dialog box on the main interface. Click on them to view details.

Effect

You can now ask questions to verify the capabilities of the travel planning assistant.

Integration via Qianfan AppBuilder Platform

Currently, the Qianfan platform supports integration via SDK or API. Build an application through AppBuilder. Each application has a unique app_id. Call the corresponding app_id in a Python file, and then you can call the Baidu Maps Python MCP Tool.

You can use the following code as a template. Call the app that has been built and published on the Qianfan platform in the form of an SDK. Download the MCP Server to your local machine and write the relative path of the file into the code.

(Note: Use actual app_id, token, query, and MCP files)

import os
import asyncio
import appbuilder
from appbuilder.core.console.appbuilder_client.async_event_handler import (
    AsyncAppBuilderEventHandler,
)
from appbuilder.mcp_server.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 "{} The temperature is {} {}".format(location, 20, unit)
    async def interrupt(self, run_context, run_response):
        thought = run_context.current_thought
        # Print in green
        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 this path 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,
        'Drive 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

After the agent's own thinking, it calls multiple tools such as the MCPServer's place search, geocoding service, and route planning service to obtain navigation routes and information, and provides travel suggestions.

Actual user request: "Please plan a one-day flower-viewing trip in Beijing for me. Try to provide a more comfortable travel arrangement, and of course, pay attention to the weather conditions."

Thinking Process

Agent Result

✨ Features

Baidu Maps API is now fully compatible with the MCP protocol, making it the first map service provider in China to support this protocol.

The MCP Server provided by Baidu Maps includes 10 API interfaces that comply with the MCP protocol standards, covering reverse geocoding, place search, route planning, etc.

It is developed based on the MCP Python SDK and MCP Typescript SDK. Any intelligent agent assistant that supports the MCP protocol (such as Claude, Cursor, and Qianfan AppBuilder) can quickly connect to it.

📦 Tools

1. Geocoding map_geocode

   • Description: Parse an address into corresponding location coordinates. The more complete the address structure and the more accurate the address content, the higher the accuracy of the parsed coordinates.
   • Parameters: address Address information
   • Output: location Latitude and longitude coordinates

2. Reverse Geocoding map_reverse_geocode

   • Description: Obtain the address description, administrative division, roads, and related POI information of a location based on its latitude and longitude coordinates.
   • Parameters:
     • latitude Latitude coordinate
     • longitude Longitude coordinate
   • Output: Semantic address information such as formatted_address, uid, addressComponent

3. Place Search map_search_places

   • Description: Support searching for place information within a city (down to the city level) or searching for nearby places within a circular area.
   • Parameters:
     • query Search keywords, which can be names or types. Separate multiple keywords with commas, e.g., query=Tiananmen,Food
     • tag Search type preference, formatted as tag=Food or tag=Food,Hotel
     • region Administrative division for the search, formatted as region=cityname or region=citycode
     • location Latitude and longitude coordinates of the center point for circular search, formatted as location=lat,lng
     • radius Radius for circular search
   • Output: A list of POIs, including name, location, address, etc.

4. Place Details Search map_place_details

   • Description: Retrieve detailed information about a POI, such as ratings and business hours (different types of POIs have different types of detailed data), based on its uid.
   • Parameters: uid Unique identifier of the POI
   • Output: Detailed information about the POI, including name, location, address, brand, price, etc.

5. Batch Route Calculation map_distance_matrix

   • Description: Calculate the route distance and travel time between origins and destinations. Currently, it supports driving, cycling, and walking.
   • Parameters:
     • origins List of latitude and longitude coordinates of origins, formatted as origins=lat,lng. Separate multiple origins with |.
     • destinations List of latitude and longitude coordinates of destinations, formatted as destinations=lat,lng. Separate multiple destinations with |.
     • mode Route calculation type, with options including driving, walking, riding. The default is driving.
   • Output: Travel time and distance for each route, including distance, duration, etc.

6. Route Planning map_directions

   • Description: Plan a travel route and estimate the travel time between an origin and a destination. You can specify travel modes such as driving, walking, cycling, or taking public transportation.
   • Parameters:
     • origin Latitude and longitude coordinates of the origin, formatted as origin=lat,lng
     • destination Latitude and longitude coordinates of the destination, formatted as destination=lat,lng
     • model Travel type, with options including driving, walking, riding, transit. The default is driving.
   • Output: Route details, including steps, distance, duration, etc.

7. Weather Query map_weather

   • Description: Query real-time weather information and 5-day forecasts by administrative division or latitude and longitude coordinates. (Users need advanced permissions to query weather by location coordinates.)
   • Parameters:
     • district_id Administrative division code
     • location Latitude and longitude coordinates, formatted as location=lng, lat
   • Output: Weather information, including temperature, weather, wind, etc.

8. IP Location map_ip_location

   • Description: Obtain the location of the current request (down to the city level) based on the requested IP. If the requested IP is IPv6, advanced permissions are required.
   • Parameters: ip Requested IP address
   • Output: Current city and the center point location of the city

9. Real-time Traffic Query map_road_traffic

   • Description: Query real-time traffic congestion. You can specify a road name and area shape (rectangle, polygon, circle) for the query.
   • Parameters:
     • model Traffic query type (optional values include road, bound, polygon, around. The 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 bottom-left and top-right corners of the area, required when model=bound (e.g., 39.9,116.4;39.9,116.4)
     • vertexes Latitude and longitude coordinates of the vertices of the polygon area, required when model=polygon (e.g., 39.9,116.4;39.9,116.4;39.9,116.4;39.9,116.4)
     • 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 (in meters), with a value range of [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

    • Description: This function can only be used when the provided API_KEY has advanced permissions. It extracts relevant POI information from the given text.
    • Parameters: text_content Text description for POI extraction (complete travel routes, itinerary plans, scenic spot recommendations, etc., e.g., "The Duku Highway and Tarim Lake in Xinjiang are so beautiful. It's also a great experience to go from Dushanzi Grand Canyon to Tianshan Mysterious Grand Canyon.")
    • Output: Relevant POI information, including name, location, etc.

📚 Documentation

Parameter Specifications

• Administrative division codes follow the Baidu adcode mapping table.
• Latitude and longitude coordinates use the gcj02ll coordinate system. For more information, refer to the Baidu Coordinate System.
• Chinese string parameters such as types should comply with the Baidu POI Type standard.

📄 License

MIT © baidu-maps

🔧 Authorization

Some advanced features in Baidu Maps MCP Server require advanced permissions to use. If needed, please contact us.

💬 Feedback

If you encounter any issues while using Baidu Maps MCP Server, please feel free to provide feedback via issue or on the Baidu Maps Open Platform. We also welcome all positive PRs. Thank you for your support and contributions!

📈 Updates