jsapi-skills MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

bmap-jsapi-gl — 2D/2.5D maps with WebGL (BMapGL)
bmap-jsapi-three — 3D maps on three.js for digital twin / environment rendering
jsapi-ui-kit — ready-made PlaceSearch and PlaceDetail components
Official — maintained by Baidu Maps team, not community reverse-engineered
Works with Claude Code, Cursor, and other agent-skill-compatible tools

라이브 데모

실제 사용 모습

jsapi-skill.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jsapi-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/baidu-maps/jsapi-skills",
        "~/.claude/skills/jsapi-skills"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "jsapi-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/baidu-maps/jsapi-skills",
        "~/.claude/skills/jsapi-skills"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "jsapi-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/baidu-maps/jsapi-skills",
        "~/.claude/skills/jsapi-skills"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "jsapi-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/baidu-maps/jsapi-skills",
        "~/.claude/skills/jsapi-skills"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "jsapi-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/baidu-maps/jsapi-skills",
        "~/.claude/skills/jsapi-skills"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "jsapi-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/baidu-maps/jsapi-skills",
          "~/.claude/skills/jsapi-skills"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add jsapi-skill -- git clone https://github.com/baidu-maps/jsapi-skills ~/.claude/skills/jsapi-skills

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: jsapi-skills

Embed a Baidu map with markers and routing into a web app

👤 Devs serving Chinese users where Baidu Maps is the default ⏱ ~30 min intermediate

언제 쓸까: Google Maps isn't viable for your audience; Baidu Maps is the standard.

사전 조건

Skill cloned — git clone https://github.com/baidu-maps/jsapi-skills ~/.claude/skills/jsapi-skills
Baidu Maps API key (ak) — lbsyun.baidu.com — create an app, enable the APIs you need

흐름

Scaffold with bmap-jsapi-gl

Use bmap-jsapi-gl skill — init a BMapGL map in <div id='map'>, center on Beijing, add markers for 5 lat/lng pairs.✓ 복사됨

→ Claude uses correct BMapGL constructors, not the old BMap JSAPI
Add routing

Now add driving directions between the first two markers.✓ 복사됨

→ DrivingRoute usage with correct event wiring

결과: A working map component in your app.

함정

Mixing legacy BMap JSAPI with BMapGL (WebGL) APIs — Skill keeps them distinct; pick one family and stick with it

함께 쓰기: filesystem

Render a 3D digital-twin scene over a Baidu Maps base layer

👤 Devs building industrial / smart-city visualizations ⏱ ~120 min advanced

언제 쓸까: You need 3D models overlaid on a geospatial base.

흐름

Set up bmap-jsapi-three

bmap-jsapi-three — base map + three.js scene, load a glTF building model at given coords.✓ 복사됨

→ Correct camera sync between Baidu base and three.js scene
Visualize data

Add a heatmap from sensor data points on top.✓ 복사됨

→ Geodata visualization layered correctly

결과: A 3D scene anchored to real-world coordinates.

Drop-in a PlaceSearch + PlaceDetail UI with jsapi-ui-kit

👤 Devs who don't want to hand-build place-search UI ⏱ ~30 min intermediate

언제 쓸까: You need a functional 'find nearby' UI fast.

흐름

Scaffold components

jsapi-ui-kit — PlaceSearch by keyword within current bounds + PlaceDetail panel.✓ 복사됨

→ Components mounted with bind to the map instance

결과: A working place-search UX without writing the UI shell.

조합

다른 MCP와 조합해 10배 효율

jsapi-skill + filesystem

Scaffold across your actual project structure

Create BaiduMap.tsx under src/components and wire it into the search page.✓ 복사됨

jsapi-skill + github

Commit integration with proper config separation

Add the map component and open a PR; keep the ak key in .env, not source.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
bmap-jsapi-gl	2D/2.5D map intent	Standard map embedding
bmap-jsapi-three	3D scene intent + models	3D visualization
jsapi-ui-kit	component intent (PlaceSearch / PlaceDetail)	Need place-search UI without building it

비용 및 제한

운영 비용

API 쿼터: Baidu Maps API has per-day quotas depending on tier
호출당 토큰: Moderate per sub-skill
금액: Free for dev usage; production tiers vary — check lbsyun.baidu.com
팁: Use staging ak for dev, production ak with quota monitoring for prod.

보안

권한, 시크릿, 파급범위

자격 증명 저장: Baidu Maps ak goes in env var / server-side; don't commit to source

데이터 외부 송신: Map tiles and API calls go to Baidu Maps servers

If users outside China hit the map, performance may be inconsistent — plan CDN and fallback strategy.
Mind China's map coordinate system (GCJ-02 / BD-09) when mixing with other data sources.

문제 해결

자주 발생하는 오류와 해결

Skill not invoked — Claude uses outdated BMap (non-GL) API

Say 'BMapGL' or 'bmap-jsapi-gl' explicitly.

확인: ls ~/.claude/skills/jsapi-skills/

SKILL.md frontmatter wrong in a sub-skill

Check the specific sub-skill folder.

확인: head ~/.claude/skills/jsapi-skills/bmap-jsapi-gl/SKILL.md

Wrong trigger keywords — three.js scene mis-aligned with base map

Use bmap-jsapi-three explicitly rather than generic 'three.js' prompts.

대안

jsapi-skills 다른 것과 비교

대안	언제 쓰나	단점/장점
Google Maps JavaScript API	Your audience is outside China	Doesn't work reliably inside China
Mapbox / MapLibre	You want OSM-based vector tiles	Different coordinate systems; more DIY

jsapi-skills