Content
# MCP-ApiPost
Based on the MCP protocol and [ApiPost Official OpenAPI](https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=23796913b176e1), an API document management tool that supports one-click access to mainstream AI editors such as Claude Code, Codex, Cursor, Windsurf, Trae, and Qoder.
## Features
- **Connection Test** - Verify MCP server status and configuration
- **Workspace Management** - View, switch team and project workspaces
- **API Interface Management** - Create, view, modify, delete interface documents
- **Incremental Update** - Support field-level precise update and deletion
- **Hierarchical Search** - Enhanced directory hierarchical search and parent-child relationship positioning
- **Recursive Browse** - Recursively search subdirectories, support depth limit
- **Multi-Dimensional Screening** - Multi-dimensional search and batch operation
- **Structured Display** - Tree structure and group display
- **Path Navigation** - Complete path display, quick positioning
- **Permission Management** - Multiple security modes, flexible operation permission control
- **Schema to Type** - Convert interface JSON Schema to TypeScript type definition and JSDoc comment
- **Front-end Friendly** - One-click get interface definition and generate TypeScript type, directly reuse in project request code
## Quick Start for Front-end
> A minimalist workflow for front-end developers: **Browse Interface → Generate TS Type → Write Request Code**.
### 1. Browse and Locate Interface
Ask directly in the AI editor:
```
List /user related interfaces for me
```
MCP will return results like:
```text
[GET] /api/v1/users/:id - Get user details (api_abc123)
[POST] /api/v1/users - Create user (api_def456)
[PUT] /api/v1/users/:id - Update user info (api_ghi789)
```
Continue to ask and view specific interface details:
```
View the details of /api/v1/users/:id interface
```
### 2. Generate Interface Request TypeScript Code
Let AI generate request function directly:
```
Generate front-end request code for /api/v1/users/:id
```
Through the `apipost_schema_to_types` tool, AI will pull the interface Schema and generate complete request type and call code:
```typescript
// types/user.ts
export interface GetUserParams {
id: number;
}
export interface GetUserResponse {
code: number;
data: {
id: number;
name: string;
email: string;
createdAt: string;
};
message: string;
}
// api/user.ts
import request from '@/utils/request';
export function getUserById(params: GetUserParams) {
return request.get<GetUserResponse>(`/api/v1/users/${params.id}`);
}
```
### 3. Directly Use in Project
Copy the generated code to the project, no need to manually maintain types:
```typescript
import { getUserById } from '@/api/user';
async function init() {
const { data } = await getUserById({ id: 1 });
console.log(data.name); // Type safety, with auto-completion
}
```
No need to manually compare interface documents to maintain types, **generate once, reuse throughout**, reduce front-end and back-end communication costs, and improve development efficiency.
## Usage Process
### 1. Download
```bash
git clone https://github.com/lniev/apipost-mcp.git
cd apipost-mcp
```
### 2. Install
#### Environment Requirements
| Environment | Version Requirement | Description |
|------|---------|------|
| **Node.js** | >= 18.0.0 | JavaScript runtime environment (MCP SDK official minimum requirement) |
| **npm** | >= 8.0.0 | Node.js package manager (usually installed with Node.js) |
#### Environment Installation Guide
**Node.js Installation:**
- Visit [Node.js official website](https://nodejs.org/) to download LTS version
- Or use package manager:
```bash
# macOS (using Homebrew)
brew install node
# Ubuntu/Debian
sudo apt update && sudo apt install nodejs npm
# CentOS/RHEL
sudo yum install nodejs npm
```
**Verify Installation:**
```bash
node --version # Should display v18.0.0 or higher version
npm --version # Should display 8.0.0 or higher version
```
#### Install Dependencies and Build
```bash
npm install && npm run build
```
### 3. Configure Environment Variables
Create `.env` file in the project root directory (already included in `.gitignore`, not submitted to Git):
```bash
touch .env
```
Edit `.env` file and add required environment variables:
```env
APIPOST_TOKEN=your_access_token_here // Replace with your own token, see below for how to obtain token
APIPOST_HOST=https://open.apipost.net // If private deployment, replace with private domain name, if you don't know what it is, share a link of an interface and fill in the link host
APIPOST_SECURITY_MODE=limited
APIPOST_DEFAULT_TEAM_NAME=Your team name
APIPOST_DEFAULT_PROJECT_NAME=Your project name
APIPOST_URL_PREFIX={{host}}
APIPOST_INLINE_COMMENTS=true
```
**Environment Variable Description:**
| Variable Name | Required | Description |
|--------|------|------|
| `APIPOST_TOKEN` | Yes | API access token |
| `APIPOST_SECURITY_MODE` | No | Security mode: `readonly`, `limited`, `full` |
| `APIPOST_DEFAULT_TEAM_NAME` | No | Default team name |
| `APIPOST_DEFAULT_PROJECT_NAME` | No | Default project name |
| `APIPOST_URL_PREFIX` | No | Interface URL prefix, automatically spliced to all new/modified interface paths, such as `{{host}}` |
| `APIPOST_INLINE_COMMENTS` | No | Whether to enable inline comments, set to `true` to generate inline comments in raw according to `desc` |
#### Security Mode Description
| Mode | Permission | Description |
|------|------|------|
| `readonly` | Read-only | Only allow viewing interface list and details, prohibit creation, modification, deletion |
| `limited` | Read-write | Allow viewing, creating, modifying interfaces, prohibit deletion operation |
| `full` | Full access | Allow all operations, including viewing, creating, modifying, deleting |
#### Obtain Token
1. [View ApiPost OpenApi official documentation](https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=0)
2. User api_token. Acquisition method: Apipost client > Workspace > Project settings > External capabilities > open API
### 4. Start Local Service
```bash
# Start service (automatically load .env)
npm run start
```
**Other available scripts:**
| Script | Description |
|------|------|
| `npm run build` | Compile TypeScript |
| `npm run start` | Start service (automatically load `.env`) |
| `npm run dev` | Run in development mode |
| `npm run watch` | Run in development mode with hot update |
| `npm run debugger` | Debug with MCP Inspector |
### 5. Configure MCP Quickly
This project provides a quick script to synchronize Apipost configuration in `mcp.json` to mainstream AI editors' MCP configuration with one click.
#### Claude Code
```bash
npm run setup:claude-code
```
Write configuration to `~/.claude.json` (globally effective, available for all projects).
#### Codex (OpenAI)
```bash
npm run setup:codex
```
Write configuration to `~/.codex/config.toml` (TOML format, globally effective).
#### Cursor
```bash
npm run setup:cursor
```
Write configuration to `~/.cursor/mcp.json` (JSON format, globally effective).
#### Windsurf
```bash
npm run setup:windsurf
```
Write configuration to `~/.windsurf/mcp.json` (JSON format, globally effective).
#### Trae
```bash
npm run setup:trae
```
Write configuration to `~/.trae/mcp.json` (JSON format, globally effective).
#### Qoder
```bash
npm run setup:qoder
```
Write configuration to `~/.qoder/mcp.json` (JSON format, globally effective).
**Note:** Ensure that environment variables in `mcp.json` are filled with real values before running.
### 6. Other Agent Client Manual Configuration mcp.json
Add to MCP configuration file:
```json
{
"mcpServers": {
"apipost": {
"command": "node",
"args": ["/absolute/path/to/apipost-mcp/dist/index.js"],
"env": {
"APIPOST_TOKEN": "your_access_token_here", // Replace with your own token
"APIPOST_HOST": "https://open.apipost.net", // If private deployment, replace with private domain name, if you don't know what it is, share a link of an interface and fill in the link host
"APIPOST_SECURITY_MODE": "limited",
"APIPOST_DEFAULT_TEAM_NAME": "Your team name",
"APIPOST_DEFAULT_PROJECT_NAME": "Your project name",
"APIPOST_URL_PREFIX": "Interface prefix can be defined as a constant, such as {{host}}",
"APIPOST_INLINE_COMMENTS": "true"
}
}
}
}
```
**Priority Description:** System environment variables > `.env` file variables. If MCP configuration file also configures the same environment variable, the MCP configuration value will override the `.env` file value.
## Project Structure
```
apipost-mcp/
├── src/
│ ├── index.ts # MCP server entry, register tools and start service
│ ├── config/ # Environment variable, security mode, URL prefix processing
│ ├── workspace/ # Workspace management (team/project initialization and switching)
│ ├── api-client/ # ApiPost OpenAPI encapsulation (axios client)
│ ├── tools/ # MCP tool definition and processor
│ │ ├── definitions.ts # Tool schema definition
│ │ └── handlers.ts # Tool business logic
│ ├── schema/ # JSON Schema processing, Body construction, response standardization, TS/JSDoc generation
│ ├── types/ # TypeScript type definition
│ └── utils/ # General utility functions (parameter conversion, field extension, JSON construction, etc.)
├── package.json
├── tsconfig.json
└── README.md
```
## Available Tools
| Tool | Function | Main Parameters |
|------|------|---------|
| `apipost_test_connection` | Connection test | `random_string` |
| `apipost_workspace` | Workspace management | `action` (required) |
| `apipost_create_folder` | Create directory | `name`, `parent_id` |
| `apipost_smart_create` | Create interface | `method`, `url`, `name` |
| `apipost_list` | Enhanced list search | `search`, `parent_id`, `target_type`, `show_structure`, `recursive`, `group_by_folder` |
| `apipost_detail` | View details | `target_id` |
| `apipost_update` | Modify interface | `target_id`, other optional |
| `apipost_delete` | Delete interface | `api_ids` |
| `apipost_schema_to_types` | Schema to TS/JSDoc | `target_id`, `output_ts`, `output_jsdoc` |
### apipost_test_connection Description
**Quick diagnosis tool**, suitable for first use or troubleshooting:
- Verify MCP server connection status
- Check environment variable configuration
- Display current workspace information
- Check operation permission and security mode
- Provide system environment details
### apipost_workspace Description
**Unified workspace management tool**, supports the following operations:
| Action | Function | Main Parameters | Description |
|--------|------|---------|------|
| `current` | View current workspace | `show_all` | Display current team, project information, optional display all available options |
| `list_teams` | List teams | `show_details` | Display all available teams, identify current team |
| `list_projects` | List projects | `team_id`, `show_details` | Display project list of specified team |
| `switch` | Switch workspace | `team_id`, `project_id` or `team_name`, `project_name` | Switch to specified team and project |
**Usage Example:**
```
# View current workspace
apipost_workspace action: "current"
# List all teams
apipost_workspace action: "list_teams" show_details: true
# List projects
apipost_workspace action: "list_projects" team_id: "your_team_id"
# Switch workspace (support by name or ID)
apipost_workspace action: "switch" team_name: "Team name" project_name: "Project name"
```
### apipost_list Parameter Description
| Parameter | Type | Description |
|------|------|------|
| `search` | string | Search keyword (interface name, URL, method, ID, description) |
| `parent_id` | string | Parent directory ID, precise search for sub-projects. "0" for root directory |
| `target_type` | string | Type filter: `api`(only interface), `folder`(only directory), `all`(all) |
| `show_structure` | boolean | Display tree structure, default false for list mode |
| `show_path` | boolean | Display complete path, default false |
| `recursive` | boolean | Recursively search subdirectories, default false |
| `depth` | number | Depth limit (cooperate with recursive), default unlimited |
| `group_by_folder` | boolean | Display by directory grouping, default false |
| `limit` | number | Display quantity limit (default 50, maximum 200) |
| `show_all` | boolean | Display all (ignore limit limit) |
### apipost_smart_create Description (Field List Driven)
Rules (Mandatory):
- `responses` should only contain `fields`, not `data`; all fields (including parent fields) must have a `desc`.
- Use field list strings for headers/query/body/cookies, with nesting using `.` and arrays using `[]` (e.g., `meta.flags.debug`, `items[].id`); example values should be real values, not JSON strings.
- Parent fields need to be explicitly declared with a `desc`, e.g., `{"key":"data","type":"object","desc":"Response Body"},{"key":"data.user","type":"object","desc":"User"},{"key":"data.user.id","type":"integer","example":1,"desc":"User ID"}`.
- Optional `APIPOST_INLINE_COMMENTS=true` generates inline comments in raw format based on `desc` (mock is always pure JSON).
- Optional `APIPOST_URL_PREFIX={{host}}` automatically appends the prefix to the URL when creating or updating an interface (avoiding manual repetition of routing constants).
Required fields: `method`, `url`, `name`. Other fields (all stringified JSON arrays/objects):
- headers/query/body/cookies: `[{"key":"X-Request-ID","type":"string","required":true,"example":"req-1","desc":"Description"}]`
- responses: `[{"name":"Success","status":200,"fields":[{"key":"code","type":"integer","example":0,"desc":"Status Code"},{"key":"data.items[].id","type":"string","example":"1","desc":"Product ID"}]}]`
- auth: `{"type":"bearer","bearer":{"key":"your_token"}}`
Field types: `string`/`integer`/`number`/`boolean`/`object`/`array`/`null`
Example (nested):
```json
"body": "[{\"key\":\"user.id\",\"type\":\"integer\",\"required\":true,\"example\":9001,\"desc\":\"User ID\"},{\"key\":\"user.profile.tags[]\",\"type\":\"string\",\"example\":\"vip\",\"desc\":\"Tags\"}]",
"responses": "[{\"name\":\"Success\",\"status\":200,\"fields\":[{\"key\":\"code\",\"type\":\"integer\",\"example\":0,\"desc\":\"Status Code\"},{\"key\":\"data.user.profile.tags[]\",\"type\":\"string\",\"example\":\"vip\",\"desc\":\"Tags\"}]}]"
```
### apipost_schema_to_types Description
**Convert JSON Schema of an interface to TypeScript type definitions and JSDoc comments**, facilitating reuse of interface types for frontend/backend. Especially suitable for frontend to quickly implement request code: after obtaining the interface type, directly copy it to the project and use it with libraries like `axios` or `fetch`.
| Parameter | Type | Required | Description |
|------|------|------|------|
| `target_id` | string | Yes | Interface ID |
| `output_ts` | boolean | No | Output TypeScript type definitions, default `true` |
| `output_jsdoc` | boolean | No | Output JSDoc comments, default `false` |
**Usage Example:**
```
# Output TypeScript types only
apipost_schema_to_types target_id: "api_123"
# Output both TypeScript and JSDoc
apipost_schema_to_types target_id: "api_123" output_ts: true output_jsdoc: true
```
**Output Structure:**
```json
{
"url": "/api/users",
"target_id": "api_123",
"method": "GET",
"request": {
"body": { "ts": "export interface RequestBody { ... }", "jsdoc": "", "mode": "json" },
"query": { "ts": "export interface Query { ... }", "jsdoc": "" }
},
"response": { "ts": "export interface Response { ... }", "jsdoc": "" }
}
```
---
## Contact Information
- Email: LnievV@outlook.com
## Related Links
- [ApiPost OpenAPI Documentation](https://docs.apipost.net/docs/detail/2a37986cbc64000?target_id=23796913b176e1)
- [MCP Protocol Specification](https://github.com/modelcontextprotocol/specification)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available