🔗 MCPLink-CLI

Lightweight Terminal MCP Protocol Conversion Gateway Engine
轻量级终端 MCP 协议转换网关引擎

🇨🇳 简体中文

🎉 项目介绍

MCPLink-CLI 是一款轻量级终端 MCP（Model Context Protocol）协议转换网关引擎。它能将任意 OpenAPI/Swagger 规范的 REST API 自动转换为 MCP 协议兼容的工具集，让 Claude Code、Cursor 等 AI 编码助手能够直接调用你的 API。

🔥 解决的核心痛点

API 无法被 AI 助手直接调用 — 传统 REST API 对 AI 编码助手不透明，MCPLink 将其转换为 MCP 协议工具
手动编写 MCP 工具适配器太繁琐 — 只需提供 OpenAPI 规范，自动生成完整的 MCP 工具定义
现有方案依赖重、配置复杂 — 零外部依赖，纯 Python 标准库实现，开箱即用
缺乏运行时监控 — 内置 TUI 仪表盘，实时查看网关状态和调用统计

✨ 自研差异化亮点

🚀 零依赖架构 — 纯 Python 3.8+ 标准库，无需 pip install 任何第三方包
📋 OpenAPI 自动转换 — 支持 OpenAPI 2.0/3.x 规范，自动生成 MCP 工具和资源
🎨 TUI 仪表盘 — 美观的终端 UI，实时显示网关统计、工具列表、配置信息
🔧 灵活的自定义映射 — 支持路径重写、分类映射、自定义工具/资源扩展
🛡️ 多认证方式 — 支持 Bearer Token、API Key、Basic Auth 等多种认证模式
📊 运行时统计 — 请求计数、成功率、平均响应时间等实时监控
🔄 智能重试 — 内置指数退避重试机制，保障请求可靠性

✨ 核心特性

特性	描述
🔗 OpenAPI 解析	支持 OpenAPI 2.0 (Swagger) 和 3.x 规范，自动提取端点、参数、请求体
🛠️ MCP 工具生成	自动将 API 端点转换为 MCP 兼容的 tool 定义，支持 JSON Schema 输入
📦 MCP 资源生成	GET 端点自动映射为 MCP 资源，支持 URI 寻址
🚀 stdio 传输	标准 MCP stdio 传输协议，无缝对接 Claude Code / Cursor
⚙️ 灵活配置	JSON 配置文件 + CLI 参数 + 环境变量，三种配置方式任选
🎨 TUI 仪表盘	彩色终端 UI，箱线图风格，工具/资源/统计一目了然
🔒 认证支持	Bearer / API Key / Basic Auth，安全对接受保护 API
📊 实时统计	请求量、成功率、响应时间、运行时长等关键指标
🔄 自动重试	指数退避重试策略，可配置最大重试次数
🏷️ 工具分类	基于 OpenAPI tags 的自动分类，支持自定义分类映射
🚫 路径过滤	支持正则表达式排除/包含特定 API 路径
✏️ 路径重写	正则表达式路径重写，灵活适配 URL 结构

🚀 快速开始

环境要求

Python 3.8+ （无需任何第三方依赖）

安装

# 克隆仓库
git clone https://github.com/gitstq/MCPLink-CLI.git
cd MCPLink-CLI

# 方式一：开发模式安装
pip install -e .

# 方式二：直接运行（无需安装）
export PYTHONPATH=src
python -m mcplink --help

核心命令

# 解析 OpenAPI 规范，查看生成的 MCP 工具
mcplink parse --spec openapi.json --base-url https://api.example.com

# 启动 MCP 网关服务器（stdio 传输）
mcplink serve --spec openapi.json --base-url https://api.example.com --auth bearer --token YOUR_TOKEN

# 列出所有注册的工具和资源
mcplink list --spec openapi.json

# 直接调用某个工具
mcplink call --name get_user --args '{"id": 1}'

# 导出工具定义为 JSON
mcplink export --spec openapi.json --output tools.json

# 初始化配置文件
mcplink init --output mcplink-config.json

# 查看 API 规范信息
mcplink info --spec openapi.json

📖 详细使用指南

配置 Claude Code 使用 MCPLink

在 .claude/settings.json 中添加：

{
  "mcpServers": {
    "my-api": {
      "command": "mcplink",
      "args": [
        "serve",
        "--spec", "/path/to/openapi.json",
        "--base-url", "https://api.example.com",
        "--auth", "bearer",
        "--token", "YOUR_API_TOKEN"
      ]
    }
  }
}

使用 JSON 配置文件

# 生成示例配置
mcplink init --output config.json

# 编辑配置后使用
mcplink serve --config config.json

配置文件示例：

{
  "name": "MyAPI-Gateway",
  "base_url": "https://api.example.com/v1",
  "auth_type": "bearer",
  "auth_value": "your-token-here",
  "timeout": 30,
  "max_retries": 3,
  "tool_prefix": "myapi_",
  "category_mapping": {
    "users": "user_management",
    "orders": "order_management"
  },
  "exclude_paths": ["/internal/.*"],
  "custom_tools": [
    {
      "name": "custom_search",
      "description": "Custom search tool",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        },
        "required": ["query"]
      },
      "http_method": "GET",
      "url_template": "https://api.example.com/search"
    }
  ]
}

环境变量配置

export MCPLINK_BASE_URL="https://api.example.com"
export MCPLINK_AUTH_TYPE="bearer"
export MCPLINK_AUTH_TOKEN="your-token"
export MCPLINK_TIMEOUT="30"
mcplink serve --spec openapi.json

💡 设计思路与迭代规划

设计理念

MCPLink-CLI 的核心理念是 "让每个 REST API 都成为 AI 的工具"。MCP 协议正在成为 AI 编码助手与外部系统交互的标准，但大量现有 API 缺少 MCP 适配层。MCPLink 通过自动解析 OpenAPI 规范，消除手动编写适配器的成本。

技术选型原因

Python 标准库 — 最大化兼容性，零安装摩擦，适合 CI/CD 和容器化部署
JSON-RPC 2.0 — MCP 协议基于 JSON-RPC，轻量且广泛支持
stdio 传输 — MCP 标准传输方式，无需网络端口，安全且简单

后续迭代计划

🔄 支持 SSE（Server-Sent Events）传输模式
📝 支持 GraphQL Schema 到 MCP 的转换
🧪 内置 API 端点健康检查和连通性测试
📊 Prometheus 指标导出
🔌 插件系统，支持自定义转换逻辑
🌐 Web Dashboard（可选的 HTTP 管理界面）

📦 打包与部署指南

作为 MCP Server 部署

MCPLink-CLI 本身就是一个 MCP Server，通过 stdio 传输与 AI 编码助手通信。无需额外打包。

# 在 Claude Code / Cursor 中配置后即可使用
# 无需启动独立服务进程

作为 Python 库使用

from mcplink.gateway import MCPGateway
from mcplink.models import ConversionConfig

config = ConversionConfig(
    base_url="https://api.example.com/v1",
    auth_type="bearer",
    auth_value="your-token",
)

gateway = MCPGateway(config)
gateway.load_openapi_file("openapi.json")

# 处理 MCP 请求
response = gateway.handle_request('{"jsonrpc":"2.0","id":1,"method":"tools/list"}')
print(response)

兼容环境

环境	支持状态
Python 3.8+	✅ 完全支持
Python 3.12+	✅ 完全支持
Windows	✅ 完全支持
macOS	✅ 完全支持
Linux	✅ 完全支持
Claude Code	✅ 完全支持
Cursor	✅ 完全支持
Windsurf	✅ 完全支持

🤝 贡献指南

欢迎贡献代码！请查看 CONTRIBUTING.md 了解详情。

提交规范

遵循 Angular Commit Convention：

feat: 新功能
fix: Bug 修复
docs: 文档更新
refactor: 代码重构
test: 测试相关
chore: 构建/工具链

📄 开源协议

本项目基于 MIT License 开源。

🇹🇼 繁體中文

🎉 專案介紹

MCPLink-CLI 是一款輕量級終端 MCP（Model Context Protocol）協議轉換閘道引擎。它能將任意 OpenAPI/Swagger 規範的 REST API 自動轉換為 MCP 協議相容的工具集，讓 Claude Code、Cursor 等 AI 編碼助手能夠直接呼叫你的 API。

🔥 解決的核心痛點

API 無法被 AI 助手直接呼叫 — 傳統 REST API 對 AI 編碼助手不透明，MCPLink 將其轉換為 MCP 協議工具
手動撰寫 MCP 工具適配器太繁瑣 — 只需提供 OpenAPI 規範，自動生成完整的 MCP 工具定義
現有方案依賴重、配置複雜 — 零外部依賴，純 Python 標準函式庫實現，開箱即用
缺乏運行時監控 — 內建 TUI 儀表板，即時查看閘道狀態和呼叫統計

✨ 自研差異化亮點

🚀 零依賴架構 — 純 Python 3.8+ 標準函式庫，無需 pip install 任何第三方套件
📋 OpenAPI 自動轉換 — 支援 OpenAPI 2.0/3.x 規範，自動生成 MCP 工具和資源
🎨 TUI 儀表板 — 美觀的終端 UI，即時顯示閘道統計、工具列表、配置資訊
🔧 靈活的自訂對映 — 支援路徑重寫、分類對映、自訂工具/資源擴展
🛡️ 多認證方式 — 支援 Bearer Token、API Key、Basic Auth 等多種認證模式
📊 運行時統計 — 請求計數、成功率、平均回應時間等即時監控
🔄 智慧重試 — 內建指數退避重試機制，保障請求可靠性

✨ 核心特性

特性	描述
🔗 OpenAPI 解析	支援 OpenAPI 2.0 (Swagger) 和 3.x 規範，自動提取端點、參數、請求體
🛠️ MCP 工具生成	自動將 API 端點轉換為 MCP 相容的 tool 定義，支援 JSON Schema 輸入
📦 MCP 資源生成	GET 端點自動對映為 MCP 資源，支援 URI 尋址
🚀 stdio 傳輸	標準 MCP stdio 傳輸協議，無縫對接 Claude Code / Cursor
⚙️ 靈活配置	JSON 配置檔 + CLI 參數 + 環境變數，三種配置方式任選
🎨 TUI 儀表板	彩色終端 UI，箱線圖風格，工具/資源/統計一目了然
🔒 認證支援	Bearer / API Key / Basic Auth，安全對接受保護 API
📊 即時統計	請求量、成功率、回應時間、運行時長等關鍵指標
🔄 自動重試	指數退避重試策略，可配置最大重試次數
🏷️ 工具分類	基於 OpenAPI tags 的自動分類，支援自訂分類對映
🚫 路徑過濾	支援正則運算式排除/包含特定 API 路徑
✏️ 路徑重寫	正則運算式路徑重寫，靈活適配 URL 結構

🚀 快速開始

環境要求

Python 3.8+ （無需任何第三方依賴）

安裝

# 克隆倉庫
git clone https://github.com/gitstq/MCPLink-CLI.git
cd MCPLink-CLI

# 方式一：開發模式安裝
pip install -e .

# 方式二：直接運行（無需安裝）
export PYTHONPATH=src
python -m mcplink --help

核心命令

# 解析 OpenAPI 規範，查看生成的 MCP 工具
mcplink parse --spec openapi.json --base-url https://api.example.com

# 啟動 MCP 閘道伺服器（stdio 傳輸）
mcplink serve --spec openapi.json --base-url https://api.example.com --auth bearer --token YOUR_TOKEN

# 列出所有註冊的工具和資源
mcplink list --spec openapi.json

# 直接呼叫某個工具
mcplink call --name get_user --args '{"id": 1}'

# 匯出工具定義為 JSON
mcplink export --spec openapi.json --output tools.json

# 初始化配置檔
mcplink init --output mcplink-config.json

# 查看 API 規範資訊
mcplink info --spec openapi.json

📖 詳細使用指南

配置 Claude Code 使用 MCPLink

在 .claude/settings.json 中添加：

{
  "mcpServers": {
    "my-api": {
      "command": "mcplink",
      "args": [
        "serve",
        "--spec", "/path/to/openapi.json",
        "--base-url", "https://api.example.com",
        "--auth", "bearer",
        "--token", "YOUR_API_TOKEN"
      ]
    }
  }
}

使用 JSON 配置檔

# 生成範例配置
mcplink init --output config.json

# 編輯配置後使用
mcplink serve --config config.json

環境變數配置

export MCPLINK_BASE_URL="https://api.example.com"
export MCPLINK_AUTH_TYPE="bearer"
export MCPLINK_AUTH_TOKEN="your-token"
export MCPLINK_TIMEOUT="30"
mcplink serve --spec openapi.json

💡 設計思路與迭代規劃

設計理念

MCPLink-CLI 的核心理念是 「讓每個 REST API 都成為 AI 的工具」。MCP 協議正在成為 AI 編碼助手與外部系統互動的標準，但大量現有 API 缺少 MCP 適配層。MCPLink 透過自動解析 OpenAPI 規範，消除手動撰寫適配器的成本。

後續迭代計畫

🔄 支援 SSE（Server-Sent Events）傳輸模式
📝 支援 GraphQL Schema 到 MCP 的轉換
🧪 內建 API 端點健康檢查和連通性測試
📊 Prometheus 指標匯出
🔌 插件系統，支援自訂轉換邏輯
🌐 Web Dashboard（可選的 HTTP 管理介面）

📦 打包與部署指南

作為 Python 函式庫使用

from mcplink.gateway import MCPGateway
from mcplink.models import ConversionConfig

config = ConversionConfig(
    base_url="https://api.example.com/v1",
    auth_type="bearer",
    auth_value="your-token",
)

gateway = MCPGateway(config)
gateway.load_openapi_file("openapi.json")

# 處理 MCP 請求
response = gateway.handle_request('{"jsonrpc":"2.0","id":1,"method":"tools/list"}')
print(response)

相容環境

環境	支援狀態
Python 3.8+	✅ 完全支援
Windows / macOS / Linux	✅ 完全支援
Claude Code / Cursor / Windsurf	✅ 完全支援

🤝 貢獻指南

歡迎貢獻程式碼！請查看 CONTRIBUTING.md 了解詳情。

📄 開源協議

本專案基於 MIT License 開源。

🇺🇸 English

🎉 Project Introduction

MCPLink-CLI is a lightweight terminal MCP (Model Context Protocol) conversion gateway engine. It automatically converts any OpenAPI/Swagger-specified REST API into an MCP-protocol-compatible toolset, enabling AI coding assistants like Claude Code and Cursor to directly invoke your APIs.

🔥 Core Pain Points Solved

APIs are invisible to AI assistants — Traditional REST APIs are opaque to AI coding tools; MCPLink bridges this gap by converting them to MCP protocol tools
Manual MCP adapter authoring is tedious — Simply provide an OpenAPI spec and MCPLink auto-generates complete MCP tool definitions
Existing solutions are heavy and complex — Zero external dependencies, pure Python standard library, works out of the box
No runtime monitoring — Built-in TUI dashboard for real-time gateway status and call statistics

✨ Differentiated Highlights

🚀 Zero-Dependency Architecture — Pure Python 3.8+ standard library, no third-party packages needed
📋 Automatic OpenAPI Conversion — Supports OpenAPI 2.0/3.x specs, auto-generates MCP tools and resources
🎨 TUI Dashboard — Beautiful terminal UI with real-time gateway stats, tool listing, and config display
🔧 Flexible Custom Mapping — Path rewriting, category mapping, custom tool/resource extensions
🛡️ Multi-Auth Support — Bearer Token, API Key, Basic Auth, and more
📊 Runtime Statistics — Request counts, success rates, average response times, and more
🔄 Smart Retry — Built-in exponential backoff retry mechanism for reliability

✨ Core Features

Feature	Description
🔗 OpenAPI Parsing	Supports OpenAPI 2.0 (Swagger) and 3.x specs, auto-extracts endpoints, params, request bodies
🛠️ MCP Tool Generation	Auto-converts API endpoints to MCP-compatible tool definitions with JSON Schema input
📦 MCP Resource Generation	GET endpoints auto-mapped to MCP resources with URI addressing
🚀 stdio Transport	Standard MCP stdio transport, seamlessly integrates with Claude Code / Cursor
⚙️ Flexible Configuration	JSON config files + CLI args + environment variables — pick your preference
🎨 TUI Dashboard	Colorful terminal UI with box-drawing style, tools/resources/stats at a glance
🔒 Auth Support	Bearer / API Key / Basic Auth for secure API integration
📊 Real-time Stats	Request volume, success rate, response time, uptime, and more
🔄 Auto Retry	Exponential backoff retry with configurable max retries
🏷️ Tool Categorization	Auto-categorization based on OpenAPI tags with custom mapping support
🚫 Path Filtering	Regex-based exclude/include for specific API paths
✏️ Path Rewriting	Regex path rewriting for flexible URL structure adaptation

🚀 Quick Start

Requirements

Python 3.8+ (no third-party dependencies required)

Installation

# Clone the repository
git clone https://github.com/gitstq/MCPLink-CLI.git
cd MCPLink-CLI

# Option 1: Development mode install
pip install -e .

# Option 2: Run directly (no install needed)
export PYTHONPATH=src
python -m mcplink --help

Core Commands

# Parse OpenAPI spec and view generated MCP tools
mcplink parse --spec openapi.json --base-url https://api.example.com

# Start MCP gateway server (stdio transport)
mcplink serve --spec openapi.json --base-url https://api.example.com --auth bearer --token YOUR_TOKEN

# List all registered tools and resources
mcplink list --spec openapi.json

# Call a specific tool directly
mcplink call --name get_user --args '{"id": 1}'

# Export tool definitions as JSON
mcplink export --spec openapi.json --output tools.json

# Initialize a config file
mcplink init --output mcplink-config.json

# View API spec information
mcplink info --spec openapi.json

📖 Detailed Usage Guide

Configure Claude Code with MCPLink

Add to .claude/settings.json:

{
  "mcpServers": {
    "my-api": {
      "command": "mcplink",
      "args": [
        "serve",
        "--spec", "/path/to/openapi.json",
        "--base-url", "https://api.example.com",
        "--auth", "bearer",
        "--token", "YOUR_API_TOKEN"
      ]
    }
  }
}

Using JSON Configuration

# Generate a sample config
mcplink init --output config.json

# Edit and use
mcplink serve --config config.json

Environment Variables

export MCPLINK_BASE_URL="https://api.example.com"
export MCPLINK_AUTH_TYPE="bearer"
export MCPLINK_AUTH_TOKEN="your-token"
export MCPLINK_TIMEOUT="30"
mcplink serve --spec openapi.json

💡 Design Philosophy & Roadmap

Design Philosophy

MCPLink-CLI's core philosophy is "Make every REST API an AI tool." The MCP protocol is becoming the standard for AI coding assistants to interact with external systems, but most existing APIs lack an MCP adaptation layer. MCPLink eliminates the cost of manual adapter authoring by automatically parsing OpenAPI specifications.

Roadmap

🔄 SSE (Server-Sent Events) transport mode
📝 GraphQL Schema to MCP conversion
🧪 Built-in API endpoint health checks
📊 Prometheus metrics export
🔌 Plugin system for custom conversion logic
🌐 Web Dashboard (optional HTTP management UI)

📦 Packaging & Deployment

As a Python Library

from mcplink.gateway import MCPGateway
from mcplink.models import ConversionConfig

config = ConversionConfig(
    base_url="https://api.example.com/v1",
    auth_type="bearer",
    auth_value="your-token",
)

gateway = MCPGateway(config)
gateway.load_openapi_file("openapi.json")

# Handle MCP requests
response = gateway.handle_request('{"jsonrpc":"2.0","id":1,"method":"tools/list"}')
print(response)

Compatibility

Environment	Status
Python 3.8+	✅ Full Support
Windows / macOS / Linux	✅ Full Support
Claude Code / Cursor / Windsurf	✅ Full Support

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License.

Built with ❤️ by MCPLink Team

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
examples		examples
src/mcplink		src/mcplink
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
quickstart.sh		quickstart.sh

Folders and files

Latest commit

History

Repository files navigation

🔗 MCPLink-CLI

🇨🇳 简体中文

🎉 项目介绍

🔥 解决的核心痛点

✨ 自研差异化亮点

✨ 核心特性

🚀 快速开始

环境要求

安装

核心命令

📖 详细使用指南

配置 Claude Code 使用 MCPLink

使用 JSON 配置文件

环境变量配置

💡 设计思路与迭代规划

设计理念

技术选型原因

后续迭代计划

📦 打包与部署指南

作为 MCP Server 部署

作为 Python 库使用

兼容环境

🤝 贡献指南

提交规范

📄 开源协议

🇹🇼 繁體中文

🎉 專案介紹

🔥 解決的核心痛點

✨ 自研差異化亮點

✨ 核心特性

🚀 快速開始

環境要求

安裝

核心命令

📖 詳細使用指南

配置 Claude Code 使用 MCPLink

使用 JSON 配置檔

環境變數配置

💡 設計思路與迭代規劃

設計理念

後續迭代計畫

📦 打包與部署指南

作為 Python 函式庫使用

相容環境

🤝 貢獻指南

📄 開源協議

🇺🇸 English

🎉 Project Introduction

🔥 Core Pain Points Solved

✨ Differentiated Highlights

✨ Core Features

🚀 Quick Start

Requirements

Installation

Core Commands

📖 Detailed Usage Guide

Configure Claude Code with MCPLink

Using JSON Configuration

Environment Variables

💡 Design Philosophy & Roadmap

Design Philosophy

Roadmap

📦 Packaging & Deployment

As a Python Library

Compatibility

🤝 Contributing

📄 License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages