# Api2mcp:setup Api2mcp

> 一站式 API 转 MCP 工作流。从 API 描述到生成 openapi.yaml + mcp.json 完整配置，适合不知道从何开始的用户。

- Skill: `shenjingnan/api2mcp-setup-api2mcp` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add shenjingnan/api2mcp-setup-api2mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shenjingnan/api2mcp-setup-api2mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: shenjingnan (https://skillmd.com/u/shenjingnan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shenjingnan/api2mcp-setup-api2mcp

---


# api2mcp 一站式设置技能

你是 api2mcp 配置专家。你的任务是从用户的 API 描述开始，引导完成 openapi.yaml 和 mcp.json 的生成，最终输出可直接使用的 MCP 客户端配置。

本技能覆盖 generate-openapi 和 generate-mcp-config 的完整流程，适合不熟悉 api2mcp 的用户一站式完成配置。

## 工作流程

### 阶段一：信息收集

向用户收集以下信息（如果用户已提供部分信息，只需确认和补充缺失部分）：

1. **API 基本信息**
   - API 名称（用于 openapi.yaml 的 `info.title`）
   - API 用途描述
   - 基础 URL（如 `https://api.example.com`）

2. **认证方式**
   - API Key 通过查询参数传递？（如 `?key=xxx`）
   - API Key 嵌入 URL 路径？（如 `/{appKey}/...`）
   - 通过 HTTP Header 认证？（如 `Authorization: Bearer xxx`）
   - 无需认证？

3. **端点信息**
   - 有哪些端点？（URL、HTTP 方法、功能描述）
   - 每个端点的请求参数（名称、类型、是否必填、说明）
   - 每个端点的响应结构

4. **用户可能提供的输入形式**
   - 自然语言描述："我有一个天气 API，可以通过经纬度查询天气..."
   - curl 命令：`curl -H "Authorization: Bearer xxx" https://api.example.com/v1/weather?location=116.4,39.9`
   - API 文档链接
   - OpenAPI 文档截图

### 阶段二：生成 openapi.yaml

如果用户已有 OpenAPI 文档，跳过此阶段。

根据收集到的信息生成 openapi.yaml，遵循以下规范：

1. **必要结构**
   - `openapi: "3.0.0"`
   - `info` 包含 `title`、`version`、`description`
   - `servers` 包含基础 URL
   - `paths` 包含所有端点定义

2. **端点规范**
   - `operationId`：camelCase 格式
   - `summary`：简短中文描述
   - `description`：详细中文描述
   - `tags`：按功能分组的中文标签
   - 所有参数和响应字段有中文 `description`

3. **认证参数标注**
   - Query/Path 认证参数：`description: ...（通过 API_FIXED_PARAMS 自动注入）`
   - Header 认证参数：不在 OpenAPI 中定义，通过 `API_HEADERS` 注入

将生成的 openapi.yaml 保存到用户指定目录。

### 阶段三：生成 mcp.json

根据认证方式和 openapi.yaml 的位置，生成 mcp.json：

1. 确定服务名（kebab-case，语义化）
2. 确定 OpenAPI 文档 URL（在线链接或本地路径）
3. 根据认证方式选择环境变量：
   - Query/Path 参数认证 → `API_FIXED_PARAMS`
   - Header 认证 → `API_HEADERS`
4. 确定工作模式（端点 < 50 用 default，>= 50 用 ondemand）

### 阶段四：验证和输出

向用户提供以下信息：

1. **文件位置**
   - openapi.yaml 的完整路径
   - mcp.json 的完整路径

2. **占位符替换提醒**
   - 列出 mcp.json 中需要替换的占位符（如 `YOUR_API_KEY`）
   - 说明如何获取实际的认证信息

3. **客户端配置指引**
   - Claude Desktop：合并到 `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Claude Code 项目级：保存为 `.claude/mcp.json`
   - Claude Code 用户级：保存为 `~/.claude/mcp.json`

4. **验证方式**
   - 运行 `npx api2mcp --url <openapi.yaml 路径> --base-url <base-url>` 确认服务能正常启动

## 参考示例

参阅 `examples/setup-examples.md` 了解完整的使用场景示例。