飞书 MCP 远程服务调用技能

通过 HTTP API 形式调用飞书官方部署的 MCP 服务，实现 AI Agent 与飞书云文档、通讯录等能力的深度集成。

🎯 核心优势

• 免部署：直接连接飞书官方 MCP 服务，无需本地配置
• 快速集成：通过 HTTP POST 请求即可调用飞书能力
• 丰富工具：支持云文档、用户搜索、文件获取等多种工具
• 灵活认证：支持 UAT（用户身份）和 TAT（应用身份）两种认证方式

📋 支持的 MCP 工具

通用工具

云文档工具

🔧 接入流程

第 1 步：初始化连接 (initialize)

import requests
import json

url = "https://mcp.feishu.cn/mcp"
headers = {
    "Content-Type": "application/json",
    "X-Lark-MCP-TAT": "t-gxxxxxxxxxxxxxxxxxxxxx",  # 或使用 X-Lark-MCP-UAT
    "X-Lark-MCP-Allowed-Tools": "create-doc,fetch-doc,update-doc"
}

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(json.dumps(result, indent=2))

第 2 步：列出可用工具 (tools/list)

payload = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
}

response = requests.post(url, headers=headers, json=payload)
tools = response.json()["result"]["tools"]
for tool in tools:
    print(f"工具名：{tool['name']}")
    print(f"描述：{tool['description']}")

第 3 步：调用工具 (tools/call)

# 示例：创建云文档
payload = {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "create-doc",
        "arguments": {
            "title": "我的测试文档",
            "content": "# 你好\n这是通过 MCP 创建的文档"
        }
    }
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()
print(json.dumps(result, indent=2))

🔐 认证方式

User Access Token (UAT)

代表用户身份，适用于需要模拟特定用户操作的场景。

获取方式： 参考 获取 user_access_token

使用示例：

headers["X-Lark-MCP-UAT"] = "u-gxxxxxxxxxxxxxxxxxxxxx"

Tenant Access Token (TAT)

代表应用身份，适用于服务端到服务端的调用场景。

获取方式：

def get_tenant_access_token(app_id, app_secret):
    url = "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal"
    payload = {
        "app_id": app_id,
        "app_secret": app_secret
    }
    response = requests.post(url, json=payload)
    return response.json()["tenant_access_token"]

# 使用
tat = get_tenant_access_token("cli_xxxxx", "xxxxxxxx")
headers["X-Lark-MCP-TAT"] = tat

📝 完整示例类

class FeishuMCPClient:
    """飞书 MCP 远程服务客户端"""
    
    def __init__(self, token, token_type="TAT", allowed_tools=None):
        """
        初始化 MCP 客户端
        
        Args:
            token: 访问凭证 (UAT 或 TAT)
            token_type: 凭证类型，"UAT" 或 "TAT"
            allowed_tools: 允许使用的工具列表
        """
        self.base_url = "https://mcp.feishu.cn/mcp"
        self.token = token
        self.token_type = token_type
        self.allowed_tools = allowed_tools or []
        self.session_id = None
        
    def _get_headers(self):
        """获取请求头"""
        headers = {
            "Content-Type": "application/json"
        }
        
        if self.token_type == "UAT":
            headers["X-Lark-MCP-UAT"] = self.token
        else:
            headers["X-Lark-MCP-TAT"] = self.token
            
        if self.allowed_tools:
            headers["X-Lark-MCP-Allowed-Tools"] = ",".join(self.allowed_tools)
            
        return headers
    
    def _request(self, method, params=None):
        """发送 MCP 请求"""
        payload = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": method
        }
        
        if params:
            payload["params"] = params
            
        response = requests.post(
            self.base_url,
            headers=self._get_headers(),
            json=payload
        )
        
        return response.json()
    
    def initialize(self):
        """初始化 MCP 会话"""
        result = self._request("initialize")
        if "result" in result:
            self.session_id = result["result"].get("protocolVersion")
            print(f"MCP 会话初始化成功，协议版本：{self.session_id}")
        return result
    
    def list_tools(self):
        """列出可用工具"""
        result = self._request("tools/list")
        if "result" in result and "tools" in result["result"]:
            tools = result["result"]["tools"]
            print(f"可用工具数量：{len(tools)}")
            for tool in tools:
                print(f"  - {tool['name']}: {tool['description']}")
        return result
    
    def call_tool(self, tool_name, arguments):
        """调用工具"""
        params = {
            "name": tool_name,
            "arguments": arguments
        }
        result = self._request("tools/call", params)
        
        # 检查是否执行失败
        if "result" in result and result["result"].get("isError"):
            error_text = result["result"]["content"][0]["text"]
            print(f"工具执行失败：{error_text}")
            
        return result
    
    # ========== 便捷方法 ==========
    
    def create_doc(self, title, content="", folder_token=None):
        """创建云文档"""
        arguments = {
            "title": title,
            "content": content
        }
        if folder_token:
            arguments["folder_token"] = folder_token
            
        return self.call_tool("create-doc", arguments)
    
    def fetch_doc(self, doc_id):
        """查看云文档"""
        return self.call_tool("fetch-doc", {"docID": doc_id})
    
    def update_doc(self, doc_id, content, block_id=None):
        """更新云文档"""
        arguments = {
            "docID": doc_id,
            "content": content
        }
        if block_id:
            arguments["block_id"] = block_id
            
        return self.call_tool("update-doc", arguments)
    
    def search_doc(self, query, creator_id=None):
        """搜索云文档"""
        arguments = {
            "query": query
        }
        if creator_id:
            arguments["creator_id"] = creator_id
            
        return self.call_tool("search-doc", arguments)
    
    def search_user(self, query):
        """搜索用户"""
        return self.call_tool("search-user", {"query": query})
    
    def list_docs(self, folder_token, page_size=20):
        """获取文档列表"""
        arguments = {
            "folder_token": folder_token,
            "page_size": page_size
        }
        return self.call_tool("list-docs", arguments)
    
    def get_comments(self, doc_id):
        """获取文档评论"""
        return self.call_tool("get-comments", {"docID": doc_id})
    
    def add_comment(self, doc_id, comment):
        """添加文档评论"""
        arguments = {
            "docID": doc_id,
            "comment": comment
        }
        return self.call_tool("add-comments", arguments)


# ============ 使用示例 ============

if __name__ == "__main__":
    # 初始化客户端
    client = FeishuMCPClient(
        token="t-gxxxxxxxxxxxxxxxxxxxxx",  # 替换为你的 TAT
        token_type="TAT",
        allowed_tools=["create-doc", "fetch-doc", "update-doc", "search-doc"]
    )
    
    # 初始化会话
    client.initialize()
    
    # 列出可用工具
    client.list_tools()
    
    # 创建文档
    result = client.create_doc(
        title="测试文档",
        content="# 你好\n这是通过 MCP 创建的文档"
    )
    print(f"创建结果：{result}")
    
    # 假设获得了文档 ID
    doc_id = result["result"]["content"][0]["text"]  # 实际需要从响应中提取
    
    # 查看文档
    doc_content = client.fetch_doc(doc_id)
    print(f"文档内容：{doc_content}")
    
    # 更新文档
    update_result = client.update_doc(
        doc_id=doc_id,
        content="\n## 更新内容\n这是追加的内容"
    )
    print(f"更新结果：{update_result}")

⚠️ 注意事项

权限申请

1. 根据工具申请权限：每个工具需要特定的 API 权限
2. UAT vs TAT：
   • UAT 适合个人场景（如搜索用户）
   • TAT 适合应用场景（如批量创建文档）
3. 权限开通：参考 申请 API 权限

工具限制

• 文件大小：fetch-file 限制 5MB 以内
• 文档类型：search-doc 仅支持 doc、docx
• 评论类型：get-comments/add-comments 仅支持文字、emoji、文档类型
• 不支持的内容：多维表格、电子表格、OKR、任务、日程等

错误处理

# 错误响应格式
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

# 常见错误码
ERROR_CODES = {
    "-32700": "Parse error - 检查 JSON 格式",
    "-32600": "Invalid Request - JSON-RPC 结构错误",
    "-32601": "Method not found - 方法不存在",
    "-32602": "Invalid params - 参数错误",
    "-32603": "Internal error - 服务端异常",
    "-32030": "Rate Limited - 请求频率超限",
    "-32011": "UAT TAT Required - 缺少认证凭证",
    "-32003": "Param Validate Error - 凭证无效或过期",
    "-32042": "Invalid Content Type - Content-Type 错误"
}

最佳实践

1. 工具列表缓存：initialize 和 tools/list 只需调用一次
2. 错误重试：遇到 500 错误可重试 1-2 次
3. 频率控制：避免短时间内大量调用（429 限流）
4. 日志记录：记录 log_id 便于问题排查

🚀 快速开始

告诉 SuperMike：

1. 创建飞书文档

"用 MCP 创建一个飞书文档，标题是'项目周报'，内容是'# 本周工作\n1. 完成功能开发\n2. 修复 3 个 bug'"

2. 查看文档内容

"读取这个飞书文档：https://xxx.feishu.cn/docx/ABC123def"

3. 搜索用户

"搜索用户'张三'，获取他的 open_id"

4. 更新文档

"在文档 https://xxx.feishu.cn/docx/ABC123def 末尾追加内容：'\n## 更新记录\n2026-03-09 更新'"

技能版本：v1.0
创建日期：2026-03-09
作者：SuperMike