Fetches YApi JSON API documentation from project URLs to help AI agents understand and integrate with client projects.
Also known as ContextDong/Yapi-Mcp, yapi-mcp, contextdong-yapi-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 2, 2026
- License
- MIT
What is YApi MCP?
YApi fetches YApi JSON API documentation from project URLs to help AI agents understand and integrate with client projects.
Summary generated from the project's README
About YApi MCP server
YApi MCP provides a way for AI coding agents to access and understand API documentation stored in YApi. By connecting to your YApi instance, the server allows agents to fetch JSON request and response schemas, which helps them write client-side code that matches your existing project requirements. This tool is designed for developers using clients like Cursor or Claude Desktop to automate the process of integrating with backend services.
Users can set up the server using uvx or pip, providing necessary credentials through environment variables, a .env file, or a .yapi-mcp.json configuration file. Authentication supports both project open tokens and login JWTs using cookies like _yapi_token and _yapi_uid. The server includes specific tools such as yapi_parse_url to extract project details from a web link, yapi_list_interfaces for searching endpoints, and yapi_get_interface to retrieve complete JSON definitions for a single API.
What you can do with it
- 1Parse API documentation from URLsAn agent can extract the base URL and project IDs directly from a pasted YApi web link.
- 2Search and list available endpointsA developer can ask an AI to find specific interfaces within a large YApi project catalog.
- 3Generate client code from schemasAn AI agent can retrieve full JSON definitions to implement client-side logic that follows the API specification.
- 4Configure server credentials dynamicallyUsers can update connection settings during a session without restarting the entire MCP process.
Written from the project's README. Every use case is checked against a quote from it.
How to install YApi MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall YApi MCP in Claude Code
$ claude mcp add --env 'YAPI_TOKEN=<YOUR_YAPI_TOKEN>' yapi-mcp -- uvx contextdong-yapi-mcpInstall YApi MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"yapi-mcp": {
"command": "uvx",
"args": [
"contextdong-yapi-mcp"
],
"env": {
"YAPI_TOKEN": "<YOUR_YAPI_TOKEN>"
}
}
}
}Install YApi MCP in VS Code
.vscode/mcp.json
{
"servers": {
"yapi-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"contextdong-yapi-mcp"
],
"env": {
"YAPI_TOKEN": "<YOUR_YAPI_TOKEN>"
}
}
}
}Install YApi MCP in VS Code CLI
$ code --add-mcp '{"name":"yapi-mcp","type":"stdio","command":"uvx","args":["contextdong-yapi-mcp"],"env":{"YAPI_TOKEN":"<YOUR_YAPI_TOKEN>"}}'Install YApi MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"yapi-mcp": {
"command": "uvx",
"args": [
"contextdong-yapi-mcp"
],
"env": {
"YAPI_TOKEN": "<YOUR_YAPI_TOKEN>"
}
}
}
}Install YApi MCP in Codex
$ codex mcp add yapi-mcp --env 'YAPI_TOKEN=<YOUR_YAPI_TOKEN>' -- uvx contextdong-yapi-mcpInstall YApi MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.yapi-mcp] command = "uvx" args = ["contextdong-yapi-mcp"] [mcp_servers.yapi-mcp.env] YAPI_TOKEN = "<YOUR_YAPI_TOKEN>"
Install YApi MCP in Gemini CLI
$ gemini mcp add -s user -e 'YAPI_TOKEN=<YOUR_YAPI_TOKEN>' yapi-mcp uvx -- contextdong-yapi-mcpInstall YApi MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"yapi-mcp": {
"command": "uvx",
"args": [
"contextdong-yapi-mcp"
],
"env": {
"YAPI_TOKEN": "<YOUR_YAPI_TOKEN>"
}
}
}
}Configuration
YAPI_TOKENRequiredSecretLogin JWT or project open token
YAPI_BASE_URLYApi host URL, e.g. https://yapi.example.com
YAPI_UIDOptional uid for login JWT cookie auth
| Name | Description | |
|---|---|---|
| YAPI_TOKEN | Login JWT or project open token | RequiredSecret |
| YAPI_BASE_URL | YApi host URL, e.g. https://yapi.example.com | |
| YAPI_UID | Optional uid for login JWT cookie auth |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablecontextdong/yapi-mcp is public and reachablegithub.com/contextdong/yapi-mcp ↗Pass
- Package names this repository as its sourcecontextdong-yapi-mcp names contextdong/yapi-mcp as sourcepypi.org/project/contextdong-yapi-mcp/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-02github.com/contextdong/yapi-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from contextdong-yapi-mcpPass
- No critical advisory in the package or its dependencies32 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubYapi-Mcp
从粘贴的 YApi 项目地址拉取接口文档(JSON 请求 / JSON 响应),供编码 Agent 自动理解并对接客户端项目的 MCP Server。
功能
- 解析 YApi 页面 URL →
base_url/project_id/interface_id - 列出 / 搜索接口,导出目录
- 拉取归一化后的请求与响应 JSON(JSON Schema / 示例)
- 鉴权:登录 JWT(Cookie
_yapi_token+_yapi_uid)或项目 open token - 动态凭证:环境变量、
.env、.yapi-mcp.json、运行时yapi_configure、或工具参数
快速接入
Cursor / Claude Desktop MCP
{
"mcpServers": {
"yapi": {
"command": "uvx",
"args": ["--from", "contextdong-yapi-mcp", "yapi-mcp"],
"env": {
"YAPI_BASE_URL": "https://yapi.example.com",
"YAPI_TOKEN": "YOUR_LOGIN_JWT_OR_PROJECT_OPEN_TOKEN"
}
}
}
}
从 Git 安装(不经 PyPI):
{
"mcpServers": {
"yapi": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/ContextDong/Yapi-Mcp",
"yapi-mcp"
],
"env": {
"YAPI_BASE_URL": "https://yapi.example.com",
"YAPI_TOKEN": "YOUR_TOKEN"
}
}
}
}
或使用 pip:
pip install contextdong-yapi-mcp
# 或: pip install git+https://github.com/ContextDong/Yapi-Mcp
配置凭证(仓库内不存放密钥)
优先级从高到低:
- 工具参数(
token、base_url) - 运行时
yapi_configure(仅当前 MCP 进程内存) - 环境变量 /
.env(YAPI_BASE_URL、YAPI_TOKEN、YAPI_UID、YAPI_COOKIE) - 配置文件
.yapi-mcp.json,或YAPI_MCP_CONFIG指向的路径
示例:
cp .env.example .env
cp .yapi-mcp.example.json .yapi-mcp.json
| 变量 | 说明 |
|---|---|
YAPI_BASE_URL |
YApi 主机,如 https://yapi.example.com |
YAPI_TOKEN |
登录 JWT 或 项目 open token |
YAPI_UID |
可选;登录 JWT 一般会自动解析 uid |
YAPI_COOKIE |
可选;原始 Cookie 头覆盖 |
YAPI_MCP_CONFIG |
可选;JSON 配置文件路径 |
切勿提交 .env、.yapi-mcp.json 或真实 token。
工具列表
| 工具 | 用途 |
|---|---|
yapi_configure / yapi_get_config |
动态配置 / 查看非敏感配置 |
yapi_parse_url |
从页面 URL 解析主机与 id |
yapi_get_project |
项目元信息 |
yapi_list_interfaces |
可搜索的接口索引 |
yapi_get_interface |
单个接口完整 JSON 定义(便于写客户端) |
yapi_export_catalog |
导出目录(可选详情) |
Agent 用法
在对话中粘贴项目地址:
根据 https://yapi.example.com/project/123/interface/api/ 对接登录相关接口
Agent 应先配置凭证(如需要),再列表 / 拉详情,最后按目标工程现有风格实现客户端。
可选 Skill:.cursor/skills/yapi-api-client/SKILL.md
本地开发
python -m pip install -e ".[dev]"
python -m pytest
python -m yapi_mcp.server
MCP Registry
- 官方名:
io.github.ContextDong/yapi-mcp - PyPI 包:
contextdong-yapi-mcp(uvx/ 命令yapi-mcp) - 说明:短名
yapi-mcp在 PyPI 上已被其他项目占用
License
MIT
YApi MCP questions
How do I add YApi MCP to Claude Code?
Run claude mcp add --env 'YAPI_TOKEN=<YOUR_YAPI_TOKEN>' yapi-mcp -- uvx contextdong-yapi-mcp in your terminal. Add --scope user to make it available in every project.
How do I add YApi MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How can I authenticate with YApi?
You can authenticate using a login JWT (via Cookie _yapi_token and _yapi_uid) or a project open token.
Can the server parse YApi URLs directly?
Yes, the server includes a tool to parse YApi page URLs into base URL, project ID, and interface ID.