# YAPI MCP Server
English | [中文](./README_zh.md)
[](https://opensource.org/licenses/MIT)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [YAPI](https://github.com/YMFE/yapi) - enabling AI assistants to manage API documentation.
## Features
| Tool | Description | YAPI API |
|------|-------------|----------|
| `yapi_list_projects` | List all configured projects | - |
| `yapi_run_auto_test` | Run automated tests | `/api/open/run_auto_test` |
| `yapi_import_data` | Import API data | `/api/open/import_data` |
| `yapi_interface_add` | Add new interface | `/api/interface/add` |
| `yapi_interface_save` | Save interface | `/api/interface/save` |
| `yapi_interface_up` | Update interface | `/api/interface/up` |
| `yapi_interface_get` | Get interface details | `/api/interface/get` |
| `yapi_interface_list` | List interfaces | `/api/interface/list` |
| `yapi_interface_list_menu` | Get interface menu | `/api/interface/list_menu` |
| `yapi_interface_add_cat` | Add interface category | `/api/interface/add_cat` |
| `yapi_interface_get_cat_menu` | Get all categories | `/api/interface/getCatMenu` |
## Installation
Clone the repository, then install dependencies and build in the project directory:
```bash
git clone <repo-url>
cd yapi-mcp
npm install
npm run build
```
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `YAPI_BASE_URL` | Yes | YAPI server URL, e.g., `https://yapi.example.com` |
| `YAPI_PROJECTS` | Yes | Project configuration in format: `projectId1:token1,projectId2:token2` |
### YAPI_PROJECTS Format
```
projectId1:token1,projectId2:token2
```
Example:
```
123:abc123token,456:def456token
```
You can get the project token from YAPI project settings page.
## Usage with Cursor
Add to your Cursor MCP configuration file:
### macOS/Linux
Edit `~/.cursor/mcp.json` and replace `/path/to/yapi-mcp` with your actual project path:
```json
{
"mcpServers": {
"yapi": {
"command": "node",
"args": ["/path/to/yapi-mcp/dist/index.js"],
"env": {
"YAPI_BASE_URL": "https://your-yapi-server.com",
"YAPI_PROJECTS": "123:your-token-here,456:another-token"
}
}
}
}
```
### Windows
Edit `%APPDATA%\Cursor\mcp.json` and use your actual project path (e.g. `C:\\Users\\YourName\\yapi-mcp\\dist\\index.js`):
```json
{
"mcpServers": {
"yapi": {
"command": "node",
"args": ["C:\\path\\to\\yapi-mcp\\dist\\index.js"],
"env": {
"YAPI_BASE_URL": "https://your-yapi-server.com",
"YAPI_PROJECTS": "123:your-token-here"
}
}
}
}
```
## Usage with Claude Desktop
Add to your Claude Desktop configuration:
### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` and replace `/path/to/yapi-mcp` with your actual project path:
```json
{
"mcpServers": {
"yapi": {
"command": "node",
"args": ["/path/to/yapi-mcp/dist/index.js"],
"env": {
"YAPI_BASE_URL": "https://your-yapi-server.com",
"YAPI_PROJECTS": "123:your-token-here"
}
}
}
}
```
### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json` with the same configuration, using your actual project path.
## Tool Examples
### List All Projects
```json
{
"name": "yapi_list_projects",
"arguments": {}
}
```
### Get Interface List (Default Project)
```json
{
"name": "yapi_interface_list",
"arguments": {
"page": 1,
"limit": 20
}
}
```
### Get Interface List (Specific Project)
```json
{
"name": "yapi_interface_list",
"arguments": {
"project": 456,
"page": 1,
"limit": 20
}
}
```
### Add New Interface
```json
{
"name": "yapi_interface_add",
"arguments": {
"catid": 456,
"title": "Get User Info",
"path": "/api/user/info",
"method": "GET",
"desc": "Get user details by ID"
}
}
```
### Get Interface Details
```json
{
"name": "yapi_interface_get",
"arguments": {
"id": 789
}
}
```
### Run Automated Tests
```json
{
"name": "yapi_run_auto_test",
"arguments": {
"project": 456,
"env_name": "dev"
}
}
```
## Development
```bash
# Clone the repository
cd yapi-mcp
# Install dependencies
npm install
# Development mode
npm run dev
# Build
npm run build
# Run
npm start
```
## Security
- Never commit your YAPI tokens to version control
- Use environment variables to store sensitive configuration
- Consider using a secrets manager for production deployments
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
