Yandex Maps MCP Server

Yandex Maps MCP 服务

用于 Yandex Maps API 的 MCP 服务。

“显示柏林地图”

“显示……的位置”

工具

1. maps_geocode

   • 将地址转换为坐标
   • 输入：
     • country（字符串）- 国家名称
     • lang（字符串）- 语言代码（例如，'ru_RU'、'en_US'）
     • state（字符串，可选）- 州、地区或省份名称
     • city（字符串，可选）- 城市或地方名称
     • district（字符串，可选）- 城市内的区或社区
     • street（字符串，可选）- 街道名称
     • house_number（字符串，可选）- 房屋或建筑物编号
   • 返回：location、formatted_address、address_components

2. maps_reverse_geocode

   • 将坐标转换为地址
   • 输入：
     • latitude（数字）
     • longitude（数字）
     • lang（字符串）- 语言代码（例如，'ru_RU'、'en_US'）
   • 返回：location、formatted_address、address_components

3. maps_render

   • 将地图渲染为 png 图像
   • 输入：
     • latitude（数字）- 地图中心的纬度坐标
     • longitude（数字）- 地图中心的经度坐标
     • latitude_span（数字）- 地图图像的高度（单位：度）
     • longitude_span（数字）- 地图图像的宽度（单位：度）
     • lang（字符串）- 语言代码（例如，'ru_RU'、'en_US'）
     • placemarks（数组，可选）- 要在地图上显示的地标数组，样式为 "pm2rdm"
       • 每个地标都应包含 latitude 和 longitude 属性
   • 返回：地图的 PNG 图像

设置

API 密钥

你需要两个 Yandex Maps API 密钥：

1. 用于地理编码功能的“JavaScript and Geocoder API”密钥
2. 用于地图渲染的 Static API 密钥

生成 API 密钥的步骤：

1. 打开 https://developer.tech.yandex.ru/ 并授权
2. 点击“Connect APIs”。选择“JavaScript and Geocoder API”并填写表单
3. 前往 API 的控制台页面并复制 API 密钥
4. 从步骤 2 开始重复操作，为 Static API 生成密钥。

本地运行

1. 克隆代码库
2. 安装依赖：

   npm install
   

3. 设置 API 密钥：

   export YANDEX_MAPS_API_KEY="your-geocoder-api-key"
   export YANDEX_MAPS_STATIC_API_KEY="your-static-api-key"
   

4. 构建服务端

   npm run build
   

5. 运行服务端：

   node dist/index.js
   

在 Claude Desktop 中使用（stdio）

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "yandex-maps": {
      "command": "node",
      "args": [
        "path/to/index.js"
      ],
      "env": {
        "YANDEX_MAPS_API_KEY": "<YOUR_GEOCODER_API_KEY>",
        "YANDEX_MAPS_STATIC_API_KEY": "<YOUR_STATIC_API_KEY>"
      }
    }
  }
}

作为 HTTP 服务使用

该服务支持 Streamable HTTP 传输，可供远程访问和 n8n 等基于 Web 的客户端使用。

启动 HTTP 服务

# Set required environment variables
export YANDEX_MAPS_API_KEY="your-geocoder-api-key"
export YANDEX_MAPS_STATIC_API_KEY="your-static-api-key"
export MCP_TRANSPORT="http"
export MCP_PORT="3000"  # Optional, defaults to 3000
export MCP_AUTH_TOKEN="your-secret-token"  # Optional but recommended

# Run the server
node dist/index.js

配置

HTTP 服务是无状态的，使用以下环境变量：

• MCP_TRANSPORT：设为 "http" 以启用 HTTP 模式（默认值："stdio"）
• MCP_PORT：HTTP 服务的端口号（默认值：3000）
• MCP_AUTH_TOKEN：可选的 Bearer 身份验证令牌。若未设置，服务将在不进行身份验证的情况下运行（不建议用于生产环境）
• YANDEX_MAPS_API_KEY：你的 Yandex Geocoder API 密钥（必需）
• YANDEX_MAPS_STATIC_API_KEY：你的 Yandex Static Maps API 密钥（必需）

身份验证

设置 MCP_AUTH_TOKEN 后，客户端必须在 Authorization 标头中提供该令牌：

Authorization: Bearer your-secret-token

在 n8n 中使用

若要与 n8n 配合使用，请按以下方式配置 MCP Client 节点：

• 服务传输方式：HTTP Streamable
• URL：http://your-server:3000（根据需要调整主机和端口）
• 身份验证：如果已配置，请添加 Bearer 令牌

已知限制

Yandex Maps Places API 没有免费套餐，这意味着 LLM 无法通过 Yandex Maps MCP 获取组织的地址和坐标。它只能对模型已知地址或坐标的地点进行地理编码，或使用用户明确输入、Web Search 或第三方 MCP 等其他来源获取相关信息。

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。