Are you the author? Sign in to claim
MCP server provides feishu related operations
飞书MCP服务器是一个基于Model Context Protocol的服务，提供飞书API集成，使AI模型能够轻松与飞书服务交互。
/src
/client # API客户端实现（底层API请求封装）
/documents # 文档相关API客户端
/bots # 机器人API客户端
/chats # 聊天相关API客户端
/services # 服务层实现（业务逻辑和错误处理）
/documents # 文档相关服务
/bots # 机器人相关服务
/chats # 聊天相关服务
/server # MCP服务器实现
/tools # MCP工具注册和实现
/typings # 类型定义
/utils # 通用工具函数
/http # HTTP服务器实现
/logger # 日志服务
/consts # 常量定义
config.ts # 配置管理
index.ts # 入口点
项目采用分层架构设计，确保关注点分离和职责明确：
客户端层（Client）
服务层（Service）
工具层（Tools）
FeiShuApiError 统一处理API错误git clone https://github.com/yourusername/feishu-mcp-server.git
cd feishu-mcp-server
pnpm install
.env文件# 飞书应用凭证（必填）
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
# 服务器配置（可选）
PORT=3344
LOG_LEVEL=info
# 开发模式（自动重启）
pnpm dev
# 或使用普通启动
pnpm start
# 构建项目
pnpm build
# 运行编译后的代码
node dist/index.js
# 方法1：使用环境变量
NODE_ENV=cli node dist/index.js
# 方法2：使用命令行参数
node dist/index.js --stdio
| 选项 | 环境变量 | 命令行参数 | 默认值 | 描述 |
|---|---|---|---|---|
| 飞书应用ID | FEISHU_APP_ID | --feishu-app-id | - | 飞书自建应用的App ID |
| 飞书应用密钥 | FEISHU_APP_SECRET | --feishu-app-secret | - | 飞书自建应用的App Secret |
| 服务器端口 | PORT | --port | 3344 | HTTP服务器端口号 |
| 日志级别 | LOG_LEVEL | --log-level | info | 日志级别(debug/info/warn/error) |
| 令牌缓存时间 | TOKEN_CACHE_DURATION | - | 7100 | 访问令牌缓存时间(秒) |
get_feishu_doc_raw获取飞书文档的原始内容。
参数：
docId - 文档ID，通常在URL中找到 (例如：feishu.cn/docx/)返回：
get_feishu_doc_info获取飞书文档的元数据信息。
参数：
docId - 文档ID返回：
send_feishu_text_message发送文本消息到飞书聊天。
参数：
chatId - 聊天IDtext - 要发送的文本内容返回：
send_feishu_card发送交互卡片到飞书聊天。
参数：
chatId - 聊天IDcardContent - 卡片内容（JSON字符串）返回：
get_feishu_chat_info获取飞书聊天的基本信息。
参数：
chatId - 聊天ID返回：
get_feishu_sheet_meta获取飞书多维表格的元数据信息。
参数：
appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)返回：
get_feishu_sheet_tables获取飞书多维表格中的数据表列表。
参数：
appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)pageSize - 每页返回的数据表数量，可选，默认为20，最大为100pageToken - 分页标记，可选，用于获取下一页数据返回：
get_feishu_sheet_views获取飞书多维表格中数据表的视图列表。
参数：
appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)tableId - 数据表IDpageSize - 每页返回的视图数量，可选，默认为20，最大为100pageToken - 分页标记，可选，用于获取下一页数据返回：
get_feishu_sheet_view获取飞书多维表格中数据表特定视图的详细信息。
参数：
appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)tableId - 数据表IDviewId - 视图ID，要获取详细信息的视图返回：
get_feishu_sheet_records获取飞书多维表格中的数据表记录。
参数：
appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)tableId - 数据表IDviewId - 视图ID，可选，不指定时使用默认视图fieldIds - 字段ID列表，可选，指定返回哪些字段filter - 过滤条件，可选，使用FQL格式sort - 排序条件，可选，使用JSON格式pageSize - 每页返回的记录数量，可选，默认为20，最大为100pageToken - 分页标记，可选，用于获取下一页数据返回：
get_feishu_sheet_record获取飞书多维表格中的单条记录。
参数：
appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)tableId - 数据表IDrecordId - 记录IDfieldIds - 字段ID列表，可选，指定返回哪些字段返回：
项目使用严格的TypeScript规范和ESLint配置：
any 类型Record<string, unknown> 替代 object 类型运行代码检查：
# 运行代码检查
pnpm lint
# 运行代码检查并修复
pnpm lint:fix
# 运行代码格式化
pnpm format
所有与飞书API相关的错误应使用 FeiShuApiError 类处理：
try {
// API操作
} catch (error) {
if (error instanceof FeiShuApiError) {
// 处理特定的API错误
logger.error(`FeiShu API Error (${error.code}): ${error.message}`);
} else {
// 处理通用错误
logger.error('Unexpected error:', error);
}
// 转换为用户友好消息
throw new FeiShuApiError('操作失败', { cause: error });
}
提交消息必须遵循以下格式：
<type>(<scope>): <subject>
例如：
feat(bot): 添加发送卡片功能fix(documents): 修复文档内容获取错误支持的类型：
feat: 新功能fix: 修复Bugdocs: 文档变更style: 代码格式调整refactor: 代码重构perf: 性能优化test: 测试相关chore: 构建过程或辅助工具的变动添加新功能的步骤：
创建客户端类
src/client/<feature>/ 目录下创建ApiClient 基类// src/client/feature/feature-client.ts
export class FeatureClient extends ApiClient {
async getFeatureData(id: string): Promise<FeatureData> {
return this.request<FeatureResponse>('/feature/get', { id });
}
}
创建服务类
src/services/<feature>/ 目录下创建// src/services/feature/feature-service.ts
export class FeatureService {
private client: FeatureClient;
constructor(config: ApiClientConfig) {
this.client = new FeatureClient(config);
}
async getFeature(id: string): Promise<Feature> {
try {
const data = await this.client.getFeatureData(id);
return this.transformData(data);
} catch (error) {
handleError(error);
}
}
}
注册服务
src/services/index.ts 中导出新服务FeiShuServices 类创建MCP工具
src/server/tools/feature-tools.ts 中创建// src/server/tools/feature-tools.ts
export function registerFeatureTools(params: ToolRegistryParams): void {
const { server, services, logger } = params;
server.tool(
'get_feishu_feature',
'Get feature from FeiShu',
{
id: z.string().describe('Feature ID'),
},
async ({ id }) => {
try {
const feature = await services.feature.getFeature(id);
return { content: [{ type: 'text', text: JSON.stringify(feature) }] };
} catch (error) {
return handleToolError(error, logger);
}
}
);
}
注册工具
src/server/tools/index.ts 中引入并注册新工具问题：API请求返回认证错误
解决方案：
问题：令牌刷新失败
解决方案：
MIT
欢迎贡献！请遵循以下步骤：
git checkout -b feature/amazing-feature）git commit -m 'feat: add some amazing feature'）git push origin feature/amazing-feature）提交PR前请确保：
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows