企业官网建设流程全解析

Klavis MCP Servers 实战指南：自建 50+ MCP 服务器的部署、OAuth 认证层与源码级解析

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本文基于 Klavis 开源仓库中 mcp_servers/README.md 展开，介绍如何在这个仓库中自建或托管运行生产级 MCP（Model Context Protocol）服务器：从 30 秒拉起一个 Docker 化的 GitHub/Gmail MCP 服务器，到理解 OAuth 包装层如何自动完成认证，再到从源码构建服务器并与 AI 框架（OpenAI Function Calling）打通。读完本文，你将能够独立完成 MCP 服务器的部署、认证与客户端接入，并能读懂其底层实现。

一、仓库定位：Production-Ready MCP Servers 集合

mcp_servers 目录是 Klavis 仓库中 MCP 服务器实现的集合，每个子目录对应一个独立服务器（如 mcp_servers/github、mcp_servers/youtube、mcp_servers/slack），覆盖 Python、TypeScript、Go 等多种语言实现。官方文档给出的定位包含三块能力：

• Self-Hosted Solutions（自托管）：每个服务器都提供 Docker 镜像，可自行部署；
• Hosted MCP Service（托管服务）：无需自建基础设施，通过klavisSDK 直接创建服务器实例；
• Enterprise OAuth（企业级 OAuth）：由 _oauth_support 目录提供的认证包装层，统一处理 Google、GitHub、Slack 等服务器的 OAuth 流程。

仓库同时提供 MCP_SERVER_GUIDE.md 作为贡献者指南，解释 MCP 服务器的设计原则（工具命名自然语言化、描述详尽、职责原子化）与测试要求（需用自然语言端到端验证工具被正确调用）。

二、快速开始：30 秒运行任意 MCP 服务器

2.1 Docker 自托管（最快方式）

以最典型的 GitHub MCP 服务器为例，README 提供了两种运行模式：

模式一：通过 Klavis OAuth 支持运行（推荐）

# Run Github MCP Server with OAuth Support through Klavis AI docker pull ghcr.io/klavis-ai/github-mcp-server:latest docker run -p 5000:5000 -e KLAVIS_API_KEY=$KLAVIS_API_KEY \ ghcr.io/klavis-ai/github-mcp-server:latest

模式二：手动注入凭证

# Or run GitHub MCP Server (manually add token) docker pull ghcr.io/klavis-ai/github-mcp-server:latest docker run -p 5000:5000 -e AUTH_DATA='{"access_token":"ghp_your_github_token_here"}' \ ghcr.io/klavis-ai/github-mcp-server:latest

关键约定：MCP 服务器运行在5000端口，MCP 协议暴露在/mcp路径上。这一约定可以从多个服务器的源码中得到印证，例如 youtube 服务器的端口配置 中YOUTUBE_MCP_SERVER_PORT环境变量默认值即为5000，且服务器同时挂载了StreamableHTTPSessionManager与 SSE 两种传输实现。

客户端接入示例（以 Cursor 为例）：

{ "mcpServers": { "github": { "url": "http://localhost:5000/mcp/" } } }

对于需要 OAuth 的服务器（如 Gmail），运行命令只需注入KLAVIS_API_KEY：

# Gmail with OAuth (requires API key) docker pull ghcr.io/klavis-ai/gmail-mcp-server:latest docker run -it -e KLAVIS_API_KEY=$KLAVIS_API_KEY \ ghcr.io/klavis-ai/gmail-mcp-server:latest

对于不需要 OAuth 的服务器（如 YouTube），则直接注入其自身的 API Key：

docker run -p 5000:5000 -e API_KEY=$API_KEY \ ghcr.io/klavis-ai/youtube-mcp-server:latest

2.2 托管服务（适合生产环境）

托管模式免去了 Docker 与 OAuth 配置的复杂度，只需一个 API Key：

pip install klavis # or npm install klavis

from klavis import Klavis klavis = Klavis(api_key="Your-Klavis-API-Key") server = klavis.mcp_server.create_server_instance("GMAIL", "user123")

创建出的实例可通过 URL 直接挂到客户端，例如：

{ "mcpServers": { "klavis-gmail": { "url": "https://gmail-mcp-server.klavis.ai/mcp/?instance_id=your-instance" }, "klavis-github": { "url": "https://github-mcp-server.klavis.ai/mcp/?instance_id=your-instance" } } }

注意 URL 中instance_id查询参数与create_server_instance创建的实例一一对应，这是托管服务实现"每用户独立凭证"的机制：不同user_id创建出的实例携带各自的 OAuth 授权数据。

三、可用服务器与 OAuth 要求

README 给出的服务器清单节选（完整 50+ 服务器以各子目录的 README 为准）：

哪些服务器需要 OAuth 可以从源码直接确认：_oauth_support/server_name.json 是唯一清单，共映射了 Airtable、Asana、GitHub、Gmail、Google 全家桶、Notion、Slack、Salesforce、Supabase 等 30 个服务器，文件注释明确写道 "Only includes servers that support OAuth authentication"。该文件同时用于 GitHub Actions 判断哪些服务器需要构建 OAuth 版本。

镜像标签规则：

• ghcr.io/klavis-ai/{server-name}-mcp-server:latest—— 带 OAuth 支持的版本（对支持 OAuth 的服务器，latest指向 OAuth 版）；
• ghcr.io/klavis-ai/{server-name}-mcp-server:{commit-id}—— 按指定 commit 构建的版本（可用作无 OAuth 的原版）。

四、从源码构建与直接运行

当需要定制服务器或不想依赖预构建镜像时，可以 clone 仓库后按各服务器的技术栈分别运行。README 给出的四种方式：

git clone https://github.com/klavis-ai/klavis.git cd klavis/mcp_servers/github # Option A: Using Docker docker build -t github-mcp . docker run -p 5000:5000 github-mcp # Option B: Run directly (Go example) go mod download go run server.go # Option C: Python servers cd ../youtube pip install -r requirements.txt python server.py # Option D: Node.js servers cd ../slack npm install npm start

各服务器在其子目录内都附有独立的 README（如 github 服务器 README、youtube 服务器 README），包含该服务器的工具列表与凭证获取方式。

4.1 源码结构示例：多语言实现风格

• Go（GitHub 服务器）：github 的 Dockerfile 采用两阶段构建——golang:1.23-alpine编译出静态二进制（CGO_ENABLED=0），最终镜像基于alpine:3.19，仅包含ca-certificates与二进制本身，EXPOSE 5000后由CMD ["./server"]启动。入口源码为 server.go。
• Python（YouTube 服务器）：server.py 基于mcpPython SDK 的Server（lowlevel API）+ Starlette 构建，通过@app.list_tools()声明工具集（转录、视频详情、搜索、频道、播放列表等），CLI 参数支持--port（默认 5000）、--log-level、--json-response（启用 StreamableHTTP 的 JSON 响应而非 SSE 流）。
• TypeScript：如 slack 服务器 等采用 Node.js 生态，npm install && npm start即可运行。

从源码结构看，Python 类服务器普遍遵循同一骨架：load_dotenv()加载.env（这正是 OAuth 包装层写入AUTH_DATA的位置）→ 创建Server实例 → 注册list_tools/call_tool处理器 → 挂载 SSE 与 StreamableHTTP 传输 → 在 5000 端口提供服务。

五、与 AI 框架集成：Function Calling 实战

README 提供了三类调用范式。

Python SDK 直接调用：

from klavis import Klavis klavis = Klavis(api_key="your-key") server = klavis.mcp_server.create_server_instance( server_name="YOUTUBE", user_id="user123" )

TypeScript SDK：

import { KlavisClient } from 'klavis'; const klavis = new KlavisClient({ apiKey: 'your-key' }); const server = await klavis.mcpServer.createServerInstance({ serverName: "Gmail", userId: "user123" });

OpenAI Function Calling 完整链路：获取 MCP 工具列表后直接作为 OpenAI 的tools参数传入：

from openai import OpenAI from klavis import Klavis klavis = Klavis(api_key="your-key") openai = OpenAI(api_key="your-openai-key") # Create server and get tools server = klavis.mcp_server.create_server_instance("YOUTUBE", "user123") tools = klavis.mcp_server.list_tools(server.server_url, format="OPENAI") # Use with OpenAI response = openai.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Summarize this video: https://..."}], tools=tools.tools )

list_tools的format="OPENAI"参数是关键细节：它把 MCP 协议的工具定义转换为 OpenAI Function Calling 所需的 schema 格式，免去了手工映射。仓库 examples/ 目录还提供了 OpenAI、Claude、LangChain、LlamaIndex、CrewAI、Google ADK、Fireworks 等框架的完整示例（如 openai-klavis 示例、langchain-klavis 示例）。

六、OAuth 认证层深度解析（_oauth_support）

这是本仓库最有工程价值的设计。README 指出 OAuth 服务器"需要额外的实现"：每个服务都要创建 OAuth 应用（redirect URL、scopes、credentials）、处理回调与 token 刷新、管理多服务密钥、应对 token 过期。Klavis 的方案是把这部分复杂性抽离成一个可叠加的 Docker 包装层。

6.1 包装架构

依据 _oauth_support/README.md：

1. Base Image：原始 MCP 服务器容器（如github-mcp-server）；
2. OAuth Wrapper：在基础镜像之上叠加认证层；
3. Transparent Proxy：认证完成后透明启动原始 MCP 服务器。

6.2 四个组件及其职责

Dockerfile.template—— 构建模板，以ARG BASE_IMAGE声明式地在任意基础镜像上叠加能力：

ARG BASE_IMAGE FROM ${BASE_IMAGE} RUN if command -v apt-get >/dev/null 2>&1; then \ apt-get update && apt-get install -y curl bash jq coreutils && apt-get clean; \ elif command -v apk >/dev/null 2>&1; then \ apk add --no-cache curl bash jq coreutils; \ elif command -v yum >/dev/null 2>&1; then \ yum install -y curl bash jq coreutils && yum clean all; \ else \ echo "Warning: Could not install dependencies."; \ fi COPY ./oauth_acquire.sh /klavis_oauth/oauth_acquire.sh COPY ./docker/entrypoint_wrapper.sh /klavis_oauth/entrypoint_wrapper.sh ENTRYPOINT ["/klavis_oauth/entrypoint_wrapper.sh", "--server-name", "${MCP_SERVER_NAME}", "--exec"] CMD ${ENTRYPOINT_COMMAND}

注意它对apt-get/apk/yum三种包管理器做了条件安装，因此同一模板可以覆盖 alpine（如 GitHub 服务器镜像）与 Debian 类的基础镜像；模板末尾通过替换 ENTRYPOINT、保留原 CMD的方式实现"无侵入"包装。

entrypoint_wrapper.sh—— 新的容器入口，核心逻辑：

• 解析--server-name（服务器名）与--exec（其后所有参数作为原始启动命令）；
• 读取SKIP_OAUTH环境变量（默认false）；
• 若SKIP_OAUTH != true，则source调用oauth_acquire.sh完成认证；
• 关键细节：只要存在AUTH_DATA，就将其追加写入工作目录的.env文件（echo "AUTH_DATA=$AUTH_DATA" >> .env），即使SKIP_OAUTH=true也会执行这一步——这让"手动注入凭证"与"OAuth 获取凭证"汇聚到同一条消费路径（Python 服务器的load_dotenv()）；
• 最后exec "${EXEC_COMMAND[@]}"以原始命令启动 MCP 服务器，环境变量全部保留。

oauth_acquire.sh—— 核心认证逻辑，完整流程如下：

1. 若AUTH_DATA已存在（外部注入），直接跳过 OAuth 流程；
2. 否则要求KLAVIS_API_KEY必须设置，缺失时报错退出（exit 128）；
3. POST https://api.klavis.ai/mcp-server/self-hosted/instance/create，请求体为{"serverName": "<服务器名>", "userId": "local_mcp_server"}，从响应中解析出instanceId与oauthUrl；
4. 用timeout 600（10 分钟）的循环每 1 秒轮询GET https://api.klavis.ai/mcp-server/instance/get-auth/$INSTANCE_ID，在第一次检测到未授权时才向终端打印认证 URL（后续轮询不再刷屏）；
5. 轮询成功则取出authData并export AUTH_DATA；超时（exit code 124）则报错退出。

server_name.json—— 内部服务器名到展示名的映射（"github": "GitHub"），既是构建系统判断"哪些服务器需要 OAuth 版本"的依据，也决定了 OAuth API 请求中的服务名。

6.3 端到端认证时序

1. Container starts → entrypoint_wrapper.sh 2. Calls oauth_acquire.sh 3. Requests Klavis API to create OAuth instance 4. Displays authentication URL to terminal 5. User completes authentication in browser 6. Polls (1s interval) to check authentication status 7. Gets AUTH_DATA, exports it and writes to .env 8. Starts original MCP server (with auth info)

6.4 环境变量速查

绕过 OAuth 的两种典型用法：

# 无认证直跑（适合不需要 OAuth 的服务或测试） docker run -it -e SKIP_OAUTH=true \ ghcr.io/klavis-ai/github-mcp-server:latest # 携带已有凭证直跑（跳过 OAuth 但沿用凭证） docker run -it -e SKIP_OAUTH=true \ -e AUTH_DATA='{"access_token":"your_token_here"}' \ ghcr.io/klavis-ai/github-mcp-server:latest

6.5 CI 构建策略

从 _oauth_support/README.md 描述的 GitHub Actions 流程看，构建遵循条件化策略：先构建基础镜像（latest+ commit SHA 双标签）→ 查询server_name.json判断是否需要 OAuth → 用podman inspect提取原容器的 entrypoint 命令 → 对需要 OAuth 的服务器构建包装版本 → 推送时给 OAuth 版本打上{commit-sha}-oauth与latest标签。这意味着**latest默认就是 OAuth 版**，需要无 OAuth 原版时应使用具体 commit SHA 标签。

七、测试与贡献规范

MCP_SERVER_GUIDE.md 对新增服务器提出了可验证的测试要求：

1. 连接真实客户端：Claude Desktop、Cursor、VS Code 均可作为 MCP 客户端；仓库内还自带低层调试工具 streamable_http_client.py，用于向服务器发送原始请求并检查直接响应；
2. 自然语言端到端测试：为每个工具构造应触发它的自然语言查询，验证客户端以正确参数调用了工具并返回预期结果；
3. 记录证据：要求以短视频或多张截图记录"查询 → 工具调用日志 → 正确结果"的完整链路，作为评审依据与活文档。

工具设计层面的规范同样值得遵循：工具名与描述使用自然语言（search_customer_by_email而非cust_find_eml）、职责原子化（read_file/write_to_file而非manage_files），并保证参数用法、可选性与默认值均有文档说明。

八、资源索引

适用前提与限制：本文所有操作以当前仓库内容为准。Docker 方式要求本地安装 Docker 并拉取ghcr.io/klavis-ai命名空间镜像；OAuth 流程依赖 Klavis API（api.klavis.ai）与一个有效的KLAVIS_API_KEY，且认证轮询窗口为 10 分钟；服务器统一监听 5000 端口、协议路径为/mcp，本地多实例并行时需自行调整端口映射（如-p 5001:5000）以避免冲突。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis