mcp-feishu-proj MCP Server

⚠️ 项目已归档 飞书项目已推出官方的MCP Server服务。

因此后续本仓库不再进行维护或更新。
请勿提交新的 Issue、Pull Request 或修改请求。
若需参考历史内容，可在只读模式下浏览本仓库。

👉 建议查看飞书项目官方文档以获得最新的支持。

MCP-飞书项目管理工具

基于MCP（Model Context Protocol）协议的飞书项目管理工具，允许AI助手通过MCP协议与飞书项目管理系统进行交互。

项目简介

本项目是一个MCP服务器实现，它封装了飞书项目管理的Open API，使AI助手能够获取飞书项目的视图列表、视图详情等信息。通过这个工具，AI助手可以帮助用户管理和查询飞书项目中的工作项。

使用方法

在支持MCP协议的客户端（如Claude桌面客户端,Cursor,Cline等）的配置文件中添加本服务器。

更多MCP客户端可参考：https://modelcontextprotocol.io/clients

以Claude桌面客户端为例，编辑claude_desktop_config.json文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

在mcpServers字段中添加以下配置：

{
  "mcpServers": {
    "feishuproj": {
      "command": "uvx",
      "args": ["mcp-feishu-proj@latest","--transport", "stdio"],
      "env": {
        "FS_PROJ_PROJECT_KEY": "your_project_key",
        "FS_PROJ_USER_KEY": "your_user_key",
        "FS_PROJ_PLUGIN_ID": "your_plugin_id",
        "FS_PROJ_PLUGIN_SECRET": "your_plugin_secret"
      }
    }
  }
}

已支持功能(欢迎贡献)

登录认证

登录及认证流程

视图功能

工作项管理

工作项搜索

获取指定的工作项列表（单空间）
获取指定的工作项列表（跨空间）
获取指定的工作项列表（单空间-复杂传参）
获取指定的工作项列表（全局搜索）
获取指定的关联工作项列表

附件管理

添加附件
文件上传
下载附件
删除附件

空间管理

角色与人员配置

获取流程角色配置详情

空间关联

获取空间关联规则列表
获取空间关联下的关联工作项实例列表
绑定空间关联的关联工作项实例
解绑空间关联的关联工作项实例

流程与节点

流程配置

子任务

添加评论
查询评论
更新评论
删除评论

其他功能

拉机器人入群
获取度量图表明细数据
获取流程角色配置详情

开发指南

开发环境配置

克隆本仓库：

git clone https://github.com/yourusername/mcp-feishu-proj.git
cd mcp-feishu-proj

安装依赖（使用uv）：

# 安装uv（如果尚未安装）
pip install uv
# 创建虚拟环境并安装依赖
uv venv
uv pip install -e .

配置说明

复制环境变量示例文件并进行配置：

cp .env.example .env

编辑.env文件，填入以下必要的配置信息：

FS_PROJ_BASE_URL=https://project.feishu.cn/
FS_PROJ_PROJECT_KEY=your_project_key
FS_PROJ_USER_KEY=your_user_key
FS_PROJ_PLUGIN_ID=your_plugin_id
FS_PROJ_PLUGIN_SECRET=your_plugin_secret

其中：

FS_PROJ_BASE_URL：飞书项目API的基础URL，默认为https://project.feishu.cn/
FS_PROJ_PROJECT_KEY：飞书项目的标识
FS_PROJ_USER_KEY：用户标识
FS_PROJ_PLUGIN_ID：飞书项目Open API的插件ID
FS_PROJ_PLUGIN_SECRET：飞书项目Open API的插件密钥

添加新功能

要添加新的飞书项目API功能，请按照以下步骤操作：

在fsprojclient.py中添加新的API方法
在server.py中使用@mcp.tool装饰器注册新的MCP工具

飞书项目Open API参考

本项目包含了飞书项目Open API的Postman集合，位于docs/open-api-postman目录下，将目录下文件导入Postman可以进行快速调试飞书项目接口：

postman_environment.json：Postman环境变量配置
postman_collection.json：Postman API集合

容器化部署指南

Docker部署

本项目提供了Docker部署支持，可以通过Docker容器运行MCP飞书项目服务。

前提条件

安装 Docker
安装 Docker Compose

使用Docker Compose运行

创建.env文件，设置必要的环境变量

cp .env.example .env

然后编辑.env文件，填入你的飞书项目相关信息：

FS_PROJ_BASE_URL=https://project.feishu.cn/
FS_PROJ_PROJECT_KEY=your_project_key
FS_PROJ_USER_KEY=your_user_key
FS_PROJ_PLUGIN_ID=your_plugin_id
FS_PROJ_PLUGIN_SECRET=your_plugin_secret

使用Docker Compose启动服务

docker-compose -f docker/docker-compose.yml up -d

这将使用ghcr.io/astral-sh/uv镜像，并挂载项目根目录到容器中，直接运行本地代码，便于开发和调试。Docker Compose会自动加载项目根目录中的.env文件作为环境变量。

查看日志

docker-compose -f docker/docker-compose.yml logs -f

停止服务

docker-compose -f docker/docker-compose.yml down

更多详细信息请参阅Docker部署文档。

Kubernetes部署

前提条件

一个可用的Kubernetes集群
已安装kubectl命令行工具
具有创建Deployment、ConfigMap和Secret的权限

部署步骤

准备Secret

首先，需要创建包含敏感信息的Secret。由于Kubernetes Secret需要使用base64编码的值，您需要对敏感信息进行编码：

# 对敏感信息进行base64编码
echo -n "your_project_key" | base64
echo -n "your_user_key" | base64
echo -n "your_plugin_id" | base64
echo -n "your_plugin_secret" | base64

然后，使用生成的base64编码值更新k8s-secret.yaml文件中的相应字段。

应用配置

依次应用以下配置文件：

# 创建ConfigMap
kubectl apply -f k8s-configmap.yaml

# 创建Secret
kubectl apply -f k8s-secret.yaml

# 创建Deployment
kubectl apply -f k8s-deployment.yaml

验证部署

检查部署状态：

# 查看Deployment状态
kubectl get deployments

# 查看Pod状态
kubectl get pods

# 查看Pod日志
kubectl logs -f <pod-name>

更多详细信息请参阅Kubernetes部署文档。

贡献指南

欢迎贡献代码、报告问题或提出改进建议。请遵循以下步骤：

Fork本仓库
创建您的特性分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建一个Pull Request

许可证

本项目采用MIT许可证。详情请参阅LICENSE文件。

⚠️ 项目已归档 飞书项目已推出官方的MCP Server服务。

因此后续本仓库不再进行维护或更新。
请勿提交新的 Issue、Pull Request 或修改请求。
若需参考历史内容，可在只读模式下浏览本仓库。

👉 建议查看飞书项目官方文档以获得最新的支持。

MCP-飞书项目管理工具

基于MCP（Model Context Protocol）协议的飞书项目管理工具，允许AI助手通过MCP协议与飞书项目管理系统进行交互。

项目简介

使用方法

在支持MCP协议的客户端（如Claude桌面客户端,Cursor,Cline等）的配置文件中添加本服务器。

更多MCP客户端可参考：https://modelcontextprotocol.io/clients

以Claude桌面客户端为例，编辑claude_desktop_config.json文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

在mcpServers字段中添加以下配置：

{
  "mcpServers": {
    "feishuproj": {
      "command": "uvx",
      "args": ["mcp-feishu-proj@latest","--transport", "stdio"],
      "env": {
        "FS_PROJ_PROJECT_KEY": "your_project_key",
        "FS_PROJ_USER_KEY": "your_user_key",
        "FS_PROJ_PLUGIN_ID": "your_plugin_id",
        "FS_PROJ_PLUGIN_SECRET": "your_plugin_secret"
      }
    }
  }
}

已支持功能(欢迎贡献)

登录认证

登录及认证流程

视图功能

工作项管理

工作项搜索

获取指定的工作项列表（单空间）
获取指定的工作项列表（跨空间）
获取指定的工作项列表（单空间-复杂传参）
获取指定的工作项列表（全局搜索）
获取指定的关联工作项列表

附件管理

添加附件
文件上传
下载附件
删除附件

空间管理

角色与人员配置

获取流程角色配置详情

空间关联

获取空间关联规则列表
获取空间关联下的关联工作项实例列表
绑定空间关联的关联工作项实例
解绑空间关联的关联工作项实例

流程与节点

流程配置

子任务

添加评论
查询评论
更新评论
删除评论

其他功能

拉机器人入群
获取度量图表明细数据
获取流程角色配置详情

开发指南

开发环境配置

克隆本仓库：

git clone https://github.com/yourusername/mcp-feishu-proj.git
cd mcp-feishu-proj

安装依赖（使用uv）：

# 安装uv（如果尚未安装）
pip install uv
# 创建虚拟环境并安装依赖
uv venv
uv pip install -e .

配置说明

复制环境变量示例文件并进行配置：

cp .env.example .env

编辑.env文件，填入以下必要的配置信息：

FS_PROJ_BASE_URL=https://project.feishu.cn/
FS_PROJ_PROJECT_KEY=your_project_key
FS_PROJ_USER_KEY=your_user_key
FS_PROJ_PLUGIN_ID=your_plugin_id
FS_PROJ_PLUGIN_SECRET=your_plugin_secret

其中：

FS_PROJ_BASE_URL：飞书项目API的基础URL，默认为https://project.feishu.cn/
FS_PROJ_PROJECT_KEY：飞书项目的标识
FS_PROJ_USER_KEY：用户标识
FS_PROJ_PLUGIN_ID：飞书项目Open API的插件ID
FS_PROJ_PLUGIN_SECRET：飞书项目Open API的插件密钥

添加新功能

要添加新的飞书项目API功能，请按照以下步骤操作：

在fsprojclient.py中添加新的API方法
在server.py中使用@mcp.tool装饰器注册新的MCP工具

飞书项目Open API参考

本项目包含了飞书项目Open API的Postman集合，位于docs/open-api-postman目录下，将目录下文件导入Postman可以进行快速调试飞书项目接口：

postman_environment.json：Postman环境变量配置
postman_collection.json：Postman API集合

容器化部署指南

Docker部署

本项目提供了Docker部署支持，可以通过Docker容器运行MCP飞书项目服务。

前提条件

安装 Docker
安装 Docker Compose

使用Docker Compose运行

创建.env文件，设置必要的环境变量

cp .env.example .env

然后编辑.env文件，填入你的飞书项目相关信息：

FS_PROJ_BASE_URL=https://project.feishu.cn/
FS_PROJ_PROJECT_KEY=your_project_key
FS_PROJ_USER_KEY=your_user_key
FS_PROJ_PLUGIN_ID=your_plugin_id
FS_PROJ_PLUGIN_SECRET=your_plugin_secret

使用Docker Compose启动服务

docker-compose -f docker/docker-compose.yml up -d

查看日志

docker-compose -f docker/docker-compose.yml logs -f

停止服务

docker-compose -f docker/docker-compose.yml down

更多详细信息请参阅Docker部署文档。

Kubernetes部署

前提条件

一个可用的Kubernetes集群
已安装kubectl命令行工具
具有创建Deployment、ConfigMap和Secret的权限

部署步骤

准备Secret

首先，需要创建包含敏感信息的Secret。由于Kubernetes Secret需要使用base64编码的值，您需要对敏感信息进行编码：

# 对敏感信息进行base64编码
echo -n "your_project_key" | base64
echo -n "your_user_key" | base64
echo -n "your_plugin_id" | base64
echo -n "your_plugin_secret" | base64

然后，使用生成的base64编码值更新k8s-secret.yaml文件中的相应字段。

应用配置

依次应用以下配置文件：

# 创建ConfigMap
kubectl apply -f k8s-configmap.yaml

# 创建Secret
kubectl apply -f k8s-secret.yaml

# 创建Deployment
kubectl apply -f k8s-deployment.yaml

验证部署

检查部署状态：

# 查看Deployment状态
kubectl get deployments

# 查看Pod状态
kubectl get pods

# 查看Pod日志
kubectl logs -f <pod-name>

更多详细信息请参阅Kubernetes部署文档。

贡献指南

欢迎贡献代码、报告问题或提出改进建议。请遵循以下步骤：

Fork本仓库
创建您的特性分支 (git checkout -b feature/amazing-feature)
提交您的更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建一个Pull Request

许可证

本项目采用MIT许可证。详情请参阅LICENSE文件。

MCP Feishu Project Manager

README Documentation

MCP-飞书项目管理工具

项目简介

使用方法

已支持功能(欢迎贡献)

登录认证

视图功能

工作项管理

工作项搜索

附件管理

空间管理

角色与人员配置

空间关联

流程与节点

流程配置

子任务

评论

其他功能

开发指南

开发环境配置

配置说明

添加新功能

飞书项目Open API参考

容器化部署指南

Docker部署

前提条件

使用Docker Compose运行

Kubernetes部署

前提条件

部署步骤

贡献指南

许可证

Quick Install

Quick Actions

Key Features

MCP Feishu Project Manager

README Documentation

MCP-飞书项目管理工具

项目简介

使用方法

已支持功能(欢迎贡献)

登录认证

视图功能

工作项管理

工作项搜索

附件管理

空间管理

角色与人员配置

空间关联

流程与节点

流程配置

子任务

评论

其他功能

开发指南

开发环境配置

配置说明

添加新功能

飞书项目Open API参考

容器化部署指南

Docker部署

前提条件

使用Docker Compose运行

Kubernetes部署

前提条件

部署步骤

贡献指南

许可证

Quick Install

Quick Actions

Key Features