Content
> ⚠️ **Project Archived**
> Feishu project has launched an official [MCP Server](https://project.feishu.cn/b/helpcenter/1p8d7djs/jdmql9oj) service.
>
> Therefore, this repository will no longer be maintained or updated.
> Please do not submit new Issues, Pull Requests, or modification requests.
> If you need to reference historical content, you can browse this repository in read-only mode.
>
> 👉 It is recommended to view the Feishu project [official documentation](https://project.feishu.cn/b/helpcenter/1p8d7djs/73n2upf3) for the latest support.
# Tool List
MCP (Model Context Protocol) based Feishu project management tool, allowing AI assistants to interact with Feishu project management systems through the MCP protocol.
## Project Overview
This project is an MCP server implementation that encapsulates the Open API of Feishu project management, enabling AI assistants to retrieve information such as view lists and view details of Feishu projects. With this tool, AI assistants can help users manage and query work items in Feishu projects.
## Usage
Add this server to the configuration file of MCP protocol supported clients (such as [Claude desktop client](https://claude.ai/download), [Cursor](https://www.cursor.com/), [Cline](https://github.com/cline/cline), etc.).
> For more MCP clients, refer to: https://modelcontextprotocol.io/clients
Take Claude desktop client as an example, edit `claude_desktop_config.json` file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following configuration to the `mcpServers` field:
```json
{
"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"
}
}
}
}
```
## Supported Features ([Contribution Welcome](#Contribution-Guide))
### Authentication
- [x] Login and authentication process
### View Functionality
- [x] Get Feishu project view list
- [x] Get view work item list
- [ ] Create fixed view
- [ ] Update fixed view
- [ ] Create condition view
- [ ] Update condition view
- [ ] Delete view
### Work Item Management
- [x] Get work item details
- [x] Get create work item metadata
- [ ] Create work item
- [ ] Update work item
- [ ] Batch update work item field values
- [ ] Delete work item
- [ ] Terminate/recover work item
- [ ] Get work item operation records
### Work Item Search
- [ ] Get specified work item list (single space)
- [ ] Get specified work item list (cross-space)
- [ ] Get specified work item list (single space - complex parameter passing)
- [ ] Get specified work item list (global search)
- [ ] Get specified associated work item list
### Attachment Management
- [ ] Add attachment
- [ ] File upload
- [ ] Download attachment
- [ ] Delete attachment
### Space Management
- [ ] Get space list
- [ ] Get space details
- [ ] Get space business line details
- [ ] Get space work item type
- [ ] Get space team members
### Role and Personnel Configuration
- [x] Get process role configuration details
### Space Association
- [ ] Get space association rule list
- [ ] Get space association associated work item instance list
- [ ] Bind space association associated work item instance
- [ ] Unbind space association associated work item instance
### Process and Node
- [ ] Get workflow details
- [ ] Get workflow details (WBS)
- [ ] Update node/schedule
- [ ] Node completion/rollback
- [ ] Status transition
### Process Configuration
- [ ] Get work item process template list
- [ ] Get process template configuration details
- [ ] Add process template
- [ ] Update process template
- [ ] Delete process template
### Subtask
- [ ] Get specified subtask list
- [ ] Get subtask details
- [ ] Create subtask
- [ ] Update subtask
- [ ] Subtask completion/rollback
- [ ] Delete subtask
### Comment
- [ ] Add comment
- [ ] Query comment
- [ ] Update comment
- [ ] Delete comment
### Other Functions
- [ ] Add robot to group
- [ ] Get metric chart details data
- [ ] Get process role configuration details
## Development Guide
## Development Environment Configuration
1. Clone this repository:
```bash
git clone https://github.com/yourusername/mcp-feishu-proj.git
cd mcp-feishu-proj
```
2. Install dependencies (using uv):
```bash
# Install uv (if not installed)
pip install uv
# Create virtual environment and install dependencies
uv venv
uv pip install -e .
```
## Configuration Instructions
1. Copy environment variable example file and configure:
```bash
cp .env.example .env
```
2. Edit `.env` file and fill in necessary configuration information:
```
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
```
Where:
- `FS_PROJ_BASE_URL`: Base URL of Feishu project API, default is https://project.feishu.cn/
- `FS_PROJ_PROJECT_KEY`: Feishu project identifier
- `FS_PROJ_USER_KEY`: User identifier
- `FS_PROJ_PLUGIN_ID`: Feishu project Open API plugin ID
- `FS_PROJ_PLUGIN_SECRET`: Feishu project Open API plugin secret
### Add New Features
To add new Feishu project API features, follow these steps:
1. Add new API methods in `fsprojclient.py`
2. Register new MCP tools in `server.py` using `@mcp.tool` decorator
### Feishu Project Open API Reference
This project includes a Postman collection of Feishu project Open API, located in `docs/open-api-postman` directory. Importing the files in this directory into Postman allows for quick debugging of Feishu project interfaces:
- `postman_environment.json`: Postman environment variable configuration
- `postman_collection.json`: Postman API collection
## Containerized Deployment Guide
### Docker Deployment
This project provides Docker deployment support, allowing you to run MCP Feishu project services in Docker containers.
#### Prerequisites
- Install [Docker](https://docs.docker.com/get-docker/)
- Install [Docker Compose](https://docs.docker.com/compose/install/)
#### Run using Docker Compose
1. Create `.env` file and set necessary environment variables
```bash
cp .env.example .env
```
Then edit `.env` file and fill in your Feishu project information:
```
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
```
2. Start service using Docker Compose
```bash
docker-compose -f docker/docker-compose.yml up -d
```
This will use `ghcr.io/astral-sh/uv` image and mount project root directory to container, directly running local code for development and debugging. Docker Compose will automatically load `.env` file in project root directory as environment variables.
3. View logs
```bash
docker-compose -f docker/docker-compose.yml logs -f
```
4. Stop service
```bash
docker-compose -f docker/docker-compose.yml down
```
For more information, refer to [Docker Deployment Document](docker/docker-README.md).
### Kubernetes Deployment
#### Prerequisites
- A usable Kubernetes cluster
- Installed kubectl command-line tool
- Permission to create Deployment, ConfigMap, and Secret
#### Deployment Steps
1. Prepare Secret
First, create a Secret containing sensitive information. Since Kubernetes Secret requires base64 encoded values, you need to encode sensitive information:
```bash
# Encode sensitive information in 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
```
Then, update corresponding fields in `k8s-secret.yaml` file using generated base64 encoded values.
2. Apply configurations
Apply the following configurations in sequence:
```bash
# Create ConfigMap
kubectl apply -f k8s-configmap.yaml
# Create Secret
kubectl apply -f k8s-secret.yaml
# Create Deployment
kubectl apply -f k8s-deployment.yaml
```
3. Verify deployment
Check deployment status:
```bash
# View Deployment status
kubectl get deployments
# View Pod status
kubectl get pods
# View Pod logs
kubectl logs -f <pod-name>
```
For more information, refer to [Kubernetes Deployment Document](k8s/k8s-README.md).
## Contribution Guide
Welcome to contribute code, report issues, or propose improvements. Please follow these steps:
1. Fork this repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Create a Pull Request
## License
This project uses MIT license. For details, refer to [LICENSE](LICENSE) file.
