magic-api-mcp
This server lets you manage magic-api instances via MCP, covering API lifecycle management, group/function/datasource administration, and built-in magic-script knowledge.
API Management
list_apis– List all interfaces (optionally filter by group)get_api– Retrieve full details (including script) by id, name, or pathcreate_api– Create a new interface; auto-creates missing groupsupdate_api_script– Update the script of an existing interfacedelete_api– Delete an interface by id, name, or pathrun_api– Execute/test an interface, returning status, headers, and body
Group Management
list_groups– List all groups/folderscreate_group– Create a new group with name, path, optional type, and optional parent
Function Management
list_functions– List all magic-script functionsget_function– Get full details of a function by id or name
Datasource Management
list_datasources– List all configured datasources
Knowledge & Search
magic_script_help– Query built-in magic-script documentation by topic (e.g.,db,http, pagination, transactions)search_code– Full-text search across all interface and function scripts
Additional Features
Read-only mode (
MAGIC_API_READONLY=true): disables all write toolsMulti-target support (http mode): manage multiple magic-api instances (e.g., prod/dev) from one deployment
Two transport modes:
stdio(local) andhttp(remote/team-shared)
Allows AI to operate a running magic-api instance, providing tools for API CRUD and execution, group/function/datasource management, and built-in magic-script knowledge.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@magic-api-mcp 列出所有接口分组,并查看getUser接口的脚本"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
magic-api MCP
让 AI 通过 MCP 操作运行中的 magic-api 实例:接口增删改查 + 运行、分组 / 函数 / 数据源管理,并内置 magic-script 知识。
支持两种部署:
stdio:本地跑,Claude 启动子进程(适合个人开发机)
http:远程服务,全公司 / 团队共用一个(适合集中部署)
安装
cd magic-api-mcp
npm install
npm run buildRelated MCP server: magic-api-mcp-server
配置(环境变量)
变量 | 必填 | 默认 | 说明 |
| 是 | — | magic-api 地址,如 |
| 否 |
| 管理端路径(非默认实例要改,如 |
| 否* | — | 静态 token |
| 否* | — | 账号密码(自动 login) |
| 否 |
| 只读模式,禁用写工具 |
| 否 | 空 | 接口路径前缀 |
| 否 |
|
|
| 否 |
| http 模式监听端口 |
| 否 |
| http 模式监听地址 |
| 否 | — | http 模式访问令牌(Bearer),不设则不鉴权 |
* 鉴权二选一(账号密码优先)。
多 target(一套服务操作多个 magic-api 实例)
如果同一个 MCP 部署需要操作多个 magic-api 实例(如 prod / dev),无需再部署多套,用 MAGIC_API_TARGETS 声明即可。
原理: 目标实例由 URL path 选定(/mcp/<target>),path 写死在 claude mcp add 命令里,整个 session 不可变,AI 没有任何工具能跨 target——选择权完全在人手里。
服务端(多 target 启动):
MAGIC_API_TARGETS=prod,dev \
MAGIC_API_TARGET_PROD_BASE=http://prod-host:9999 \
MAGIC_API_TARGET_PROD_TOKEN=静态令牌 \
MAGIC_API_TARGET_PROD_READONLY=true \
MAGIC_API_TARGET_DEV_BASE=http://dev-host:9999 \
MAGIC_API_TARGET_DEV_USERNAME=admin \
MAGIC_API_TARGET_DEV_PASSWORD=密码 \
MAGIC_API_TRANSPORT=http \
MAGIC_API_ACCESS_TOKEN=团队令牌 \
node dist/index.js每 target 的字段(前缀为 MAGIC_API_TARGET_<NAME>_,NAME 转为大写):
变量 | 必填 | 默认 | 说明 |
| target 必填 | — | magic-api 地址 |
| 否 |
| 管理端路径 |
| 否* | — | 静态 token |
| 否* | — | 账号密码(自动 login) |
| 否 |
| 只读模式 |
| 否 | 空 | 接口路径前缀 |
同事连接(每人按需选 target):
# 连生产
claude mcp add --transport http magic-api-prod http://部署机:3111/mcp/prod \
--header "Authorization: Bearer 团队令牌"
# 连开发
claude mcp add --transport http magic-api-dev http://部署机:3111/mcp/dev \
--header "Authorization: Bearer 团队令牌"target 名仅允许
[A-Za-z0-9_-]+,同一 session 锁定一个 target。不设
MAGIC_API_TARGETS时仍为单 target(legacy 模式),现有部署零改动。stdio 不支持多 target(无 path 路由),设了
MAGIC_API_TARGETS又用 stdio 会启动报错。全局
MAGIC_API_ACCESS_TOKEN守卫所有 path;per-target 隔离由 URL 完成。
模式一:stdio(本地,个人用)
Claude 直接启动本地进程。
Claude Code
claude mcp add magic-api --scope user \
-e MAGIC_API_BASE=http://your-magic-api-host:9999 \
-e MAGIC_API_WEB=/your-app/magic/dev \
-e MAGIC_API_USERNAME=your-username \
-e MAGIC_API_PASSWORD=your-password \
-- node /绝对路径/magic-api-mcp/dist/index.jsClaude Desktop(claude_desktop_config.json)
{
"mcpServers": {
"magic-api": {
"command": "node",
"args": ["/绝对路径/magic-api-mcp/dist/index.js"],
"env": {
"MAGIC_API_BASE": "http://your-magic-api-host:9999",
"MAGIC_API_WEB": "/your-app/magic/dev",
"MAGIC_API_USERNAME": "your-username",
"MAGIC_API_PASSWORD": "your-password"
}
}
}
}模式二:http(远程,团队共用)
在一台服务器(如内网)常驻运行,所有人连同一个地址。凭据集中在服务端,客户端无需知道 magic-api 密码。
直接启动
MAGIC_API_TRANSPORT=http \
MAGIC_API_HTTP_PORT=3111 \
MAGIC_API_ACCESS_TOKEN=团队令牌 \
MAGIC_API_BASE=http://your-magic-api-host:9999 \
MAGIC_API_WEB=/your-app/magic/dev \
MAGIC_API_USERNAME=your-username \
MAGIC_API_PASSWORD=your-password \
node dist/index.js常驻(pm2)
pm2 start dist/index.js --name magic-api-mcp
pm2 save && pm2 startupDocker
docker build -t magic-api-mcp .
docker run -d -p 3111:3111 \
-e MAGIC_API_BASE=http://your-magic-api-host:9999 \
-e MAGIC_API_WEB=/your-app/magic/dev \
-e MAGIC_API_USERNAME=your-username -e MAGIC_API_PASSWORD=your-password \
-e MAGIC_API_ACCESS_TOKEN=团队令牌 \
magic-api-mcp同事的 Claude Code 连接
claude mcp add --transport http magic-api http://部署机:3111/mcp \
--header "Authorization: Bearer 团队令牌"http 模式为无状态(每个请求独立 transport),适合低频管理操作。强烈建议设置
MAGIC_API_ACCESS_TOKEN,否则任何能访问该端口的人都能操作 magic-api。
工具一览
接口:
list_apisget_apicreate_apiupdate_api_scriptdelete_apirun_api分组:
list_groupscreate_group函数:
list_functionsget_function数据源:
list_datasources知识:
magic_script_helpsearch_code
只读模式(MAGIC_API_READONLY=true)下,写工具被隐藏并在调用时拒绝。
冒烟测试
手动脚本(只读,对真实实例):
MAGIC_API_BASE=... MAGIC_API_WEB=... MAGIC_API_USERNAME=... MAGIC_API_PASSWORD=... \
node scripts/smoke.mjs或接进 Claude 后试:「列出所有接口分组,看看 getPrintData 的脚本」。
开发
npm test # 单元 + 集成(73 测试)
npm run dev # tsx 直跑(stdio)
npm run buildAvailable Tools
13 toolscreate_apiA
创建接口。自动建立缺失分组。返回 id 与完整运行路径 runPath。
Inputs: path (required), method (required), name (required), group (required), +2 more.
create_groupC
创建分组。type 默认 api。返回新分组 id。
Inputs: name (required), path (required), type, parent.
delete_apiC
删除接口。ref 可为 id/name/path。
Inputs: ref (required).
get_apiA
获取接口详情(含脚本)。ref 可为 id、name 或 path。
Inputs: ref (required).
get_functionA
获取函数详情(含脚本)。ref 为 id 或 name。
Inputs: ref (required).
list_apisB
列出所有接口,含 id/name/method/path/runPath/group。可按分组名过滤。
Inputs: group.
list_datasourcesB
列出所有数据源。
Inputs: no named parameters.
list_functionsB
列出所有 magic-script 函数。
Inputs: no named parameters.
list_groupsB
列出 magic-api 中所有分组(folder)。
Inputs: no named parameters.
magic_script_helpB
查询 magic-script 用法(db/http/response/env 模块、请求变量、分页、事务等)。
Inputs: topic (required).
run_apiA
运行(测试)接口。向真实路径发请求并返回 status/headers/body。被测接口的错误不算工具错误。
Inputs: path (required), method (required), params, body, +1 more.
search_codeC
在所有接口/函数脚本中全局搜索关键词。
Inputs: keyword (required).
update_api_scriptB
更新接口脚本。ref 可为 id/name/path。
Inputs: ref (required), script (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a distinct resource or action (e.g., create_api, delete_api, get_api, run_api, search_code, magic_script_help). There is no overlap or ambiguity between tools, as they clearly differentiate between APIs, groups, functions, datasources, and help.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_api, list_groups, update_api_script). Even magic_script_help uses a noun but still fits the style. No mixing of conventions.
13 tools is well-scoped for a server managing APIs, groups, functions, datasources, and scripts. It covers the essential operations without being overwhelming or too sparse.
While CRUD for APIs is covered (create, delete, get, update_script), groups and functions lack update and delete operations. Datasources only have list. The presence of run_api and search_code adds value, but missing lifecycle operations on groups and functions are notable gaps.
Maintenance
Related MCP Connectors
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Query and update Teable records, manage tables, and access the Teable API with AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive development tools for Magic-API including documentation lookup, API testing, resource management, debugging with breakpoints, backup operations, and code search capabilities. Enables developers to efficiently build, test, and maintain Magic-API projects through natural language interactions.33 PyPI33MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Magic-API development environment, supporting script syntax query, API management, debugging, and knowledge search for efficient development.MIT
- AlicenseAqualityDmaintenanceExposes Swagger/OpenAPI API documentation to AI models, enabling exploration, search, and interaction with endpoints, schemas, and execution of API calls.1413 npm2MIT
- AlicenseAqualityDmaintenanceExposes the full Kong Gateway Admin API as MCP tools, enabling AI assistants to manage services, routes, consumers, plugins, upstreams, and more.13MIT