Content
⚠️ **Project Archived**
The Feishu Project has launched the 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 refer to 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.
# MCP-Feishu Project Management Tool
Feishu project management tool based on the MCP (Model Context Protocol) protocol, allowing AI assistants to interact with the Feishu project management system through the MCP protocol.
## Project Introduction
This project is an MCP server implementation that encapsulates the Open API of Feishu project management, enabling AI assistants to obtain information such as the view list and view details of Feishu projects. Through this tool, AI assistants can help users manage and query work items in Feishu projects.
## Usage
Add this server to the configuration file of a client that supports the MCP protocol (such as [Claude desktop client](https://claude.ai/download), [Cursor](https://www.cursor.com/), [Cline](https://github.com/cline/cline), etc.).
> More MCP clients can be found at: https://modelcontextprotocol.io/clients
Taking the Claude desktop client as an example, edit the `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 ([Welcome to Contribute](#Contribution-Guide))
### Login Authentication
- [x] Login and authentication process
### View Features
- [x] Get Feishu project view list
- [x] Get view work item list
- [ ] Create fixed view
- [ ] Update fixed view
- [ ] Create conditional view
- [ ] Update conditional 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/restore work item
- [ ] Get work item operation history
### Work Item Search
- [ ] Get the specified work item list (single space)
- [ ] Get the specified work item list (cross-space)
- [ ] Get the specified work item list (single space - complex parameters)
- [ ] Get the specified work item list (global search)
- [ ] Get the specified associated work item list
### Attachment Management
- [ ] Add attachment
- [ ] Upload file
- [ ] Download attachment
- [ ] Delete attachment
### Space Management
- [ ] Get space list
- [ ] Get space details
- [ ] Get business line details under space
- [ ] Get work item type under space
- [ ] Get team members under space
### Role and Personnel Configuration
- [x] Get process role configuration details
### Space Association
- [ ] Get space association rule list
- [ ] Get associated work item instance list under space association
- [ ] Bind associated work item instance of space association
- [ ] Unbind associated work item instance of space association
### Process and Node
- [ ] Get workflow details
- [ ] Get workflow details (WBS)
- [ ] Update node/schedule
- [ ] Node complete/rollback
- [ ] Status flow
### Process Configuration
- [ ] Get process template list under work item
- [ ] Get process template configuration details
- [ ] Add process template
- [ ] Update process template
- [ ] Delete process template
### Subtask
- [ ] Get the specified subtask list
- [ ] Get subtask details
- [ ] Create subtask
- [ ] Update subtask
- [ ] Subtask complete/rollback
- [ ] Delete subtask
### Comments
- [ ] Add comment
- [ ] Query comments
- [ ] Update comment
- [ ] Delete comment
### Other Features
- [ ] Pull robot into group
- [ ] Get metric chart detail 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 already installed)
pip install uv
# Create a virtual environment and install dependencies
uv venv
uv pip install -e .
```
## Configuration Instructions
1. Copy the environment variable example file and configure it:
```bash
cp .env.example .env
```
2. Edit the `.env` file and fill in the following 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`: The base URL of the Feishu Project API, defaults to https://project.feishu.cn/
- `FS_PROJ_PROJECT_KEY`: The identifier of the Feishu project
- `FS_PROJ_USER_KEY`: User identifier
- `FS_PROJ_PLUGIN_ID`: The plugin ID of the Feishu Project Open API
- `FS_PROJ_PLUGIN_SECRET`: The plugin secret of the Feishu Project Open API
### Adding New Features
To add new Feishu Project API features, follow these steps:
1. Add a new API method in `fsprojclient.py`
2. Register the new MCP tool using the `@mcp.tool` decorator in `server.py`
### Feishu Project Open API Reference
This project includes a Postman collection of the Feishu Project Open API, located in the `docs/open-api-postman` directory. Importing the files in this directory into Postman allows for quick debugging of the Feishu Project interface:
- `postman_environment.json`: Postman environment variable configuration
- `postman_collection.json`: Postman API collection
## Containerized Deployment Guide
### Docker Deployment
This project provides Docker deployment support, and the MCP Feishu project service can be run through 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 a `.env` file and set the necessary environment variables
```bash
cp .env.example .env
```
Then edit the `.env` file and fill in your Feishu project related 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. Use Docker Compose to start the service
```bash
docker-compose -f docker/docker-compose.yml up -d
```
This will use the `ghcr.io/astral-sh/uv` image and mount the project root directory into the container to directly run the local code, which is convenient for development and debugging. Docker Compose will automatically load the `.env` file in the project root directory as environment variables.
3. View logs
```bash
docker-compose -f docker/docker-compose.yml logs -f
```
4. Stop the service
```bash
docker-compose -f docker/docker-compose.yml down
```
For more details, please refer to [Docker Deployment Documentation](docker/docker-README.md).
### Kubernetes Deployment
#### Prerequisites
- An available Kubernetes cluster
- kubectl command-line tool installed
- Permissions to create Deployment, ConfigMap, and Secret
#### Deployment Steps
1. Prepare Secret
First, you need to create a Secret containing sensitive information. Since Kubernetes Secret requires base64 encoded values, you need to encode the sensitive information:
```bash
# Base64 encode sensitive information
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, use the generated base64 encoded values to update the corresponding fields in the `k8s-secret.yaml` file.
2. Apply Configuration
Apply the following configuration files 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 the 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 details, please refer to [Kubernetes Deployment Documentation](k8s/k8s-README.md).
## Contribution Guide
Contributions, bug reports, and feature requests are welcome. 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 the branch (`git push origin feature/amazing-feature`)
5. Create a Pull Request
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
