Baidu Map MCP Server for Windsurf: Setup & Config

What you can do with Baidu Map in Windsurf

A single Baidu Maps bridge for routes, places, weather, traffic, and address conversion.

• Compare travel distances and durations for several origin-destination pairs.
• Extract places from travel notes when advanced permissions are available.

Before you start: Baidu Map in Windsurf

• Node.js and npx for this launch option
• A Baidu Maps server-side API key
• An MCP-compatible client

This is the README's Node.js configuration. Its Python alternative uses python -m mcp_server_baidu_maps and BAIDU_MAPS_API_KEY instead. SSE is recommended in the README, but no direct SSE server URL is provided in the supplied text. Advanced POI extraction requires extra permission.

Baidu Map Windsurf configuration

1. Choose Windsurf configuration scope

   For Baidu Map MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Baidu Map MCP Server to Windsurf

   Use the mcp-baidu-maps entry below in mcpServers. Keep Baidu Map MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Baidu Map MCP Server in Windsurf

   Baidu Map MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-baidu-maps": {
      "command": "npx",
      "args": [
        "-y",
        "@baidumap/mcp-server-baidu-map"
      ],
      "env": {
        "BAIDU_MAP_API_KEY": "<Baidu Maps server-side API key>"
      }
    }
  }
}

Baidu Map tools available to Windsurf

Baidu Map's stored tool list documents 11 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

map_geocode

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_geocode.

Resolve an address into geographic coordinates.

map_reverse_geocode

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_reverse_geocode.

Look up address and place context for geographic coordinates.

map_search_places

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_search_places.

map_place_details

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_place_details.

map_distance_matrix

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_distance_matrix.

Compare route distances and durations for multiple origins and destinations; named this way in the structured input.

map_directions

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_directions.

Plan travel between two points and return route options, distance, and duration.

map_weather

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_weather.

map_ip_location

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_ip_location.

map_road_traffic

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_road_traffic.

map_poi_extract

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_poi_extract.

Identify places in free text; advanced permission is required.

map_directions_matrix

After refreshing Baidu Map in Windsurf settings, check Cascade's tool list for map_directions_matrix.

Batch route planning for driving, walking, or cycling; the matrix tool name shown in the README.

Baidu Map: full stored tool descriptions

Troubleshooting Baidu Map in Windsurf

• Check npx @baidumap/mcp-server-baidu-map (Node.js/npm) on the machine running Windsurf's MCP integration for Baidu Map MCP Server; refresh MCP and inspect Cascade's tools.
• Check BAIDU_MAP_API_KEY for Baidu Map MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Baidu Map MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires a Baidu Maps server-side API key.
• Known limitation: Text-to-place extraction needs advanced permission.
• Known limitation: The input sources use different names for the route-matrix tool.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions