Feishu Tokens is an MCP server that automates token management for Feishu (Lark) API integrations. It handles authentication flows including app-level and user-level access tokens, automatically refreshing them before they expire. Key features of Feishu Tokens: - Automatic fetching and refreshing of `app_access_token` for Feishu App API access - Refresh capability for `user_access_token` using refresh tokens - Session-based configuration for secure credential management via MCP sessions - Built on Smithery framework with support for `.env` file configuration - In-memory token caching with guidance for Redis/database persistence in production - Expiry tracking with clear details on token validity periods

飞书 Access Token MCP

本项目是一个基于 Smithery 和 Python 构建的 MCP (Model-Context-Protocol) 服务，用于管理并自动刷新飞书的 app_access_token 和 user_access_token。

该服务将飞书的 Token 管理逻辑封装成一个 MCP 工具。客户端（如 AI Agent）可以通过配置会话（Session）并调用此工具，来获取一个有效的访问令牌，无需关心其内部的获取机制。

功能特性

项目结构

feishu_user_token_mcp/
├── .env                 # 环境变量配置文件
├── .env.example         # 环境变量配置示例文件
├── .gitignore
├── README.md
├── debug.md             # 调试和故障排查指南
├── pyproject.toml       # Smithery 配置文件
├── smithery.yaml
├── simple_test.py       # 简单测试脚本
├── direct_test.py       # 直接测试脚本
├── test_server.py       # 服务器测试脚本
├── http_client_test.py  # HTTP 客户端测试脚本
├── check_env.py         # 环境变量检查脚本
└── src/
    └── hello_server/
        ├── __init__.py
        └── server.py    # MCP 服务器定义和核心逻辑

环境要求

安装与设置

1. 克隆仓库：

   git clone 
   cd feishu_user_token_mcp
   

2. 配置环境变量： 复制 .env.example 文件并重命名为 .env，然后添加您的飞书应用凭证：

   cp .env.example .env
   

   FEISHU_APP_ID=your_app_id
   FEISHU_APP_SECRET=your_app_secret
   

3. 安装 uv (如果尚未安装): 这是一个高效的 Python 包管理器。

   pip install uv
   

4. 创建虚拟环境并安装依赖： uv 会自动创建虚拟环境并安装项目依赖。

   uv sync
   

核心功能

1. 获取飞书 App Token

通过 get_feishu_app_token 工具获取有效的飞书应用访问令牌。该工具会自动处理令牌的刷新。

2. 刷新飞书 User Token

通过 refresh_feishu_user_token 工具使用刷新令牌获取新的用户访问令牌。

如何运行和测试

1. 检查环境变量配置

使用以下命令测试环境变量配置：

uv run python check_env.py

2. 直接测试 Token 管理功能

使用以下命令直接测试核心 Token 管理功能：

uv run python direct_test.py

3. 本地开发运行

使用以下命令启动本地开发服务器：

uv run dev

服务器将在 http://127.0.0.1:8081 上运行。

4. 在 Smithery Playground 中测试

为了方便地测试 MCP 服务，您可以使用 Smithery Playground。它提供了一个图形界面来配置会话和调用工具。

运行以下命令：

uv run playground

或者直接使用：

npx @smithery/cli playground --port 8081

此命令会将您的本地服务器通过 ngrok 安全地连接到 Smithery Playground。您会得到一个 URL，在浏览器中打开它即可开始测试。

在 Playground 中的测试步骤：

1. 配置会话 (Configure Session)： 在 Playground 页面的 "Session Config" 部分，填入您的飞书应用凭证：

   {
     "app_id": "你的飞书 app_id",
     "app_secret": "你的飞书 app_secret"
   }
   

或者

> "Call the get_feishu_app_token tool" 要测试用户 token 刷新功能： > "刷新用户 token"

3. 查看结果： 模型会调用相应的工具，您将在界面上看到返回的结果。

用于生产环境

此 MVP (最小可行产品) 实现使用内存中的字典来存储不同会话的 TokenManager 实例。这对于开发和大多数场景是足够的，但请注意：

对于需要跨实例共享状态或在重启后保留状态的生产环境，建议将 token_manager_cache 替换为外部的持久化存储，例如：

故障排查

如果在开发或部署过程中遇到问题，请查看 debug.md 文件，其中包含了详细的故障排查指南，包括：

部署到 Smithery

准备好部署了吗？将您的代码推送到 GitHub 并部署到 Smithery：

1. 在 github.com/new 创建一个新的仓库

2. 初始化 git 并推送到 GitHub：

   git add .
   git commit -m "Initial commit: Feishu Access Token Manager"
   git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
   git push -u origin main
   

3. 在 smithery.ai/new 部署您的服务器

API 参考

get_feishu_app_token

获取有效的飞书应用访问令牌。

参数：

返回值：

{
  "app_access_token": "t-g1049oiTYL4Q23JHXCL4DST4ICYXMQC42V6JY57Y",
  "expires_at": 1758718220.6939602
}

refresh_feishu_user_token

使用刷新令牌获取新的用户访问令牌。

参数：

返回值：

{
  "access_token": "u-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "refresh_token": "ur-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "expires_in": 7200,
  "token_type": "Bearer",
  "scope": "contact:user.base:readonly"
}