MCP Connector for Feishu Project Management Utility

This package serves as an MCP (Model Context Protocol) server bridge, facilitating secure and structured communication between an AI assistant and the Feishu Project Management ecosystem via its native Open API.

Core Functionality Overview

This MCP server wrapper abstracts the complexity of Feishu's Project API, enabling AI clients to query project metadata, retrieve structured lists of views, and manipulate individual work items programmatically.

Setup and Integration

To utilize this service, configure it within the settings of any compatible MCP client (e.g., Claude Desktop Client, Cursor, or Cline). Refer to the official client documentation for precise configuration steps.

For a list of supporting clients, visit: https://modelcontextprotocol.io/clients

For the Claude Desktop Client, modify the configuration file (claude_desktop_config.json): - macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows Path: %APPDATA%\Claude\claude_desktop_config.json

Inject the following configuration into the mcpServers section:

{ "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 Capabilities Matrix (Enhancement Suggestions Welcome)

Authentication

• [x] Secure session initiation and credential validation

Project View Operations

• [x] Enumeration of available project views (lists)
• [x] Retrieval of specific view contents (work item lists)
• [ ] Provisioning of static/pinned views
• [ ] Modification of static/pinned view definitions
• [ ] Creation of dynamic/filter-based views
• [ ] Alteration of dynamic/filter-based view definitions
• [ ] Decommissioning of any defined view

Work Item Lifecycle Management

• [x] Fetching granular details for individual work items
• [x] Querying required metadata for new work item creation
• [ ] Instantiation of new work items
• [ ] Updating existing work item attributes
• [ ] Bulk modification of field values across multiple items
• [ ] Item archival or deletion
• [ ] Status control: Completion or Reinstatement
• [ ] Auditing and retrieving historical activity logs for items

Item Search Utilities

• [ ] Scoped item querying within a single workspace
• [ ] Cross-workspace item retrieval
• [ ] Advanced parameter-driven single-workspace querying
• [ ] Global indexing and search functionality
• [ ] Retrieval of linked/related items

Artifact Handling

• [ ] Attaching new secondary materials
• [ ] Secure file upload mechanisms
• [ ] Downloading associated artifacts
• [ ] Removing attached artifacts

Workspace Configuration

• [ ] Listing accessible organizational spaces
• [ ] Retrieving specific workspace configuration details
• [ ] Detailing business unit structures within a space
• [ ] Fetching supported item types for a given space
• [ ] Listing space occupants/team members

Role Definitions

• [x] Accessing details of defined workflow roles

Workspace Linking/Relationships

• [ ] Fetching rules governing inter-workspace connections
• [ ] Listing related work item instances based on linkage rules
• [ ] Establishing a binding to a related work item instance
• [ ] Removing a binding from a related work item instance

Workflow and Stage Management

• [ ] Retrieving detailed workflow blueprints
• [ ] Retrieving WBS (Work Breakdown Structure) views of workflows
• [ ] Adjusting stage timings or milestones
• [ ] Signaling stage completion or rollback
• [ ] Orchestrating state transitions

Workflow Templating

• [ ] Listing available process templates associated with an item
• [ ] Retrieving the configuration schema for a template
• [ ] Deploying a new process template
• [ ] Modifying an existing process template
• [ ] Retiring a process template

Subtask Management

• [ ] Querying a list of subordinate tasks
• [ ] Retrieving subtask specifics
• [ ] Creating new subtasks
• [ ] Updating subtask properties
• [ ] Marking subtasks as complete/reverting status
• [ ] Removing subtasks

Communication Logging

• [ ] Posting new commentary/notes
• [ ] Retrieving historical discussion threads
• [ ] Modifying existing entries
• [ ] Deleting commentary entries

Miscellaneous Services

• [ ] Invoking bots into communication channels
• [ ] Accessing metrics and detailed data for reporting dashboards
• [ ] Accessing details of defined workflow roles (Duplicate entry for completeness)

Development Workflow

Environment Setup

1. Obtain a local copy of the repository:

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

1. Dependency Installation (Using uv):

bash

Install uv if missing

pip install uv

Initialize isolated environment and install dependencies in editable mode

uv venv uv pip install -e .

Configuration Details

1. Initialize environment variables from the template:

bash cp .env.example .env

1. Populate the .env file with necessary credentials:

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 primary endpoint for the Feishu Project API (defaults to https://project.feishu.cn/). - FS_PROJ_PROJECT_KEY: Unique identifier for the target project. - FS_PROJ_USER_KEY: Identifier for the authenticating user. - FS_PROJ_PLUGIN_ID: The Plugin ID registered with Feishu Project API. - FS_PROJ_PLUGIN_SECRET: The corresponding secret key for the plugin.

Adding New Tool Methods

To extend functionality:

1. Implement the new API call logic within fsprojclient.py.
2. Register the new capability using the @mcp.tool decorator in server.py.

Feishu Project API Reference Materials

This repository includes a Postman collection in the docs/open-api-postman directory for rapid interface testing:

• postman_environment.json: Defines required environment variables for Postman.
• postman_collection.json: The complete API call collection.

Deployment Strategies

Docker Containerization

This project supports deployment via Docker containers.

Prerequisites

• Docker
• Docker Compose

Running with Docker Compose

1. Set up the environment file:

bash cp .env.example .env

Edit .env to supply your Feishu project credentials as detailed above.

1. Launch the service detached:

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

This command utilizes the ghcr.io/astral-sh/uv image, mounts the local source code, and automatically loads environment variables from the .env file, ideal for development/debugging.

1. Monitor execution output:

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

1. Terminate the running service:

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

Consult [docker/docker-README.md] for more comprehensive containerization insights.

Kubernetes Deployment

Prerequisites

• An operational Kubernetes cluster.
• kubectl configured for cluster interaction.
• Permissions to deploy ClusterResources (Deployment, ConfigMap, Secret).

Deployment Sequence

1. Secret Preparation: Sensitive data must be base64 encoded before inclusion in Kubernetes Secrets:

bash

Encode secrets

echo -n "your_project_key" | base64 echo -n "your_user_key" | base64 echo -n "your_plugin_id" | base64 echo -n "your_plugin_secret" | base64

Substitute the resulting encoded strings into the k8s-secret.yaml template.

1. Resource Application: Apply manifests in sequence:

bash

Deploy configuration map

kubectl apply -f k8s-configmap.yaml

Deploy secrets

kubectl apply -f k8s-secret.yaml

Deploy the service workload

kubectl apply -f k8s-deployment.yaml

1. Verification Steps: Confirm successful provisioning:

bash

Check deployment health

kubectl get deployments

Check running pod count

kubectl get pods

View live output from a specific pod

kubectl logs -f

Refer to [k8s/k8s-README.md] for detailed Kubernetes operational instructions.

Contribution Guidelines

We welcome code contributions, bug reports, and feature requests. To contribute, please follow the standard open-source workflow:

1. Fork this repository.
2. Create a dedicated feature branch (git checkout -b feature/new-enhancement).
3. Commit your changes (git commit -m 'Feature: Added support for X').
4. Push the branch to your fork (git push origin feature/new-enhancement).
5. Submit a formal Pull Request against the main branch.

License

This project is distributed under the permissive MIT License. See the [LICENSE] file for full terms.