coze-mcp-for-openclaw

 # Coze MCP Server For OpenClaw Configure Coze workflows and start using them in OpenClaw immediately! This project allows you to quickly: 1. Encapsulate your Coze workflows into an MCP service and run it locally 2. Use the `make_skills` script in the script to quickly configure skills using workflows for your OpenClaw This project aims to provide a simple and efficient way to add extra skills to OpenClaw using Coze workflows. Compared to directly installing OpenClaw skills, using Coze workflows for skill management has the following advantages: 1. **No environment dependencies**: Many OpenClaw skills involve running Python scripts or other scripts, which inevitably encounter environment dependency issues. Using Coze to support skills only requires using HTTP calls, eliminating the need for environment configuration. 2. **Simple skill testing**: For OpenClaw, testing a skill's availability requires either letting OpenClaw use the skill directly or reading and following the skill's content step-by-step, which is complex. Using Coze workflows, users can test the workflow in Coze to verify the skill's availability. ## Coze Configuration Before using this project, create an independent workspace in Coze and obtain its ID. This project will scan all published workflows under this workspace as extra skills for OpenClaw. **Note**: Please configure description text for each workflow and its inputs and outputs to help callers understand when to call and how to call. - [Coze Workspace](https://www.coze.cn/space/) ## Features - Based on the MCP standard protocol, compatible with all AI clients that support MCP - Automatically obtain all published workflows in the specified workspace - Expose each workflow as an MCP tool - Support workflow list query, detail view, and execution - Provide workflow cache refresh function - Return debug URL and resource usage - Provide scripts to quickly add/update/delete skills, making it convenient for OpenClaw users to manage skills ## Quick Start ### 1. Install uv If you haven't installed uv, install it: **Windows (PowerShell):** ```powershell powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **macOS/Linux:** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 2. Create a virtual environment and install dependencies ```bash uv venv uv sync ``` ### 3. Configure environment variables Copy the `.env.example` file to `.env` and fill in the following configurations: ``` # Coze API configuration COZE_API_KEY=your_coze_api_key_here WORKSPACE_ID=your_workspace_id_here OPENCLAW_SKILLS_DIR=~/.openclaw/skills ``` - `COZE_API_KEY`: Your Coze API key (personal access token) - `WORKSPACE_ID`: The Workspace ID you want to load workflows from - `OPENCLAW_SKILLS_DIR`: OpenClaw skills directory ### 4. Run the MCP server ```bash uv run coze-mcp ``` Or run the Python file directly: ```bash uv run python coze_mcp.py ``` ## MCP Tool Description This server provides the following MCP tools: ### 1. list_workflows List all available workflows in the workspace. **Return example:** ``` Found 3 published workflows: - **workflow_1** (ID: 73505836754923***) Description: This is an example workflow - **workflow_2** (ID: 73505836754924***) Description: Another workflow ``` ### 2. run_workflow_by_name Execute a workflow by name. **Parameters:** - `workflow_name` (required): Workflow name - `parameters` (optional): Workflow input parameters, in JSON string format **Example:** ```json { "workflow_name": "my_workflow", "parameters": "{\"input\": \"Hello World\"}" } ``` **Return example:** ``` Workflow execution successful! **Execution result:** { "output": "Processing result" } **Resource usage:** - Input Token: 50 - Output Token: 100 - Total Token: 150 **Debug link:** https://www.coze.cn/work_flow?execute_id=xxx ``` ### 3. get_workflow_info Get detailed information about a specified workflow. **Parameters:** - `workflow_name` (required): Workflow name **Return example:** ``` **Workflow information** - **Name:** my_workflow - **ID:** 73505836754923*** - **Description:** This is an example workflow - **Icon:** https://example.com/icon.png - **Creation time:** 1752060786 - **Update time:** 1752060827 ``` ### 4. refresh_workflows Refresh the workflow list cache. **Return example:** ``` Successfully refreshed the workflow list, loaded 10 workflows. ``` ## Configure in AI Client ### OpenClaw Configure OpenClaw using mcporter, add the following content to the configuration file: ```json { "coze-mcp": { "baseUrl": "http://localhost:33123/mcp" } } ``` Ensure the Coze MCP server is running, and OpenClaw will automatically connect to the service. ## Skill Generation Script This project provides a script to generate OpenClaw skill files for all published workflows. ### Environment variable configuration Add the following configuration to the `.env` file: ``` OPENCLAW_SKILLS_DIR=C:\Users\YourUsername\.openclaw\skills ``` - `OPENCLAW_SKILLS_DIR`: Skill file storage directory, the script will create a corresponding skill folder for each workflow in this directory ### Run the script ```bash # Create new skills (existing folders will be skipped) uv run python script/make_skills.py # Update existing skill files uv run python script/make_skills.py --update # Delete specified skills (support comma-separated multiple) uv run python script/make_skills.py --remove workflow1,workflow2 # Delete all skills uv run python script/make_skills.py --remove all ``` ### Script function 1. Read the `OPENCLAW_SKILLS_DIR` environment variable from `.env`, if not configured, exit with an error 2. Call the Coze API to obtain all published workflows and their parameter details 3. Create a folder named after the workflow in the skills directory for each workflow 4. Use the `skill_template.md` template to generate the `SKILL.md` file ### Parameter description | Parameter | Description | |------|------| | No parameters | Create new skills, existing folders will be skipped | | `--update` | Update existing skill folders | | `--remove NAMES` | Delete specified skill folders, support comma-separated multiple names, or use `all` to delete all (need secondary confirmation before deletion) | ## Project Structure ``` coze-mcp/ ├── coze_mcp.py # MCP server main file ├── pyproject.toml # Project configuration file ├── .python-version # Python version configuration ├── .env # Environment variable configuration ├── .env.example # Environment variable example ├── skill_template.md # Skill file template ├── script/ │ └── make_skills.py # Skill generation script └── README.md # Project documentation ``` ## Technology Stack - Python 3.12+ - MCP Python SDK (mcp) - httpx (asynchronous HTTP client) - python-dotenv (environment variable management) - uv (package management tool) ## API Description ### Get Workflow List - **Interface**: `GET https://api.coze.cn/v1/workflows` - **Permission**: `listWorkflow` - **Parameters**: - `workspace_id`: Workspace ID (required) - `page_num`: Page number (required, minimum value is 1) - `page_size`: Number of items per page (optional, 1-30, default 10) - `publish_status`: Publish status (optional, default `published_online`) ### Execute Workflow - **Interface**: `POST https://api.coze.cn/v1/workflow/run` - **Permission**: `run` - **Parameters**: - `workflow_id`: Workflow ID (required) - `parameters`: Workflow input parameters (optional, JSON object) - `bot_id`: Associated bot ID (optional) - `is_async`: Whether to execute asynchronously (optional, default false) ## Notes 1. Ensure your Coze API key has access to the specified Workspace 2. Ensure the API key has `listWorkflow` and `run` permissions 3. The service will automatically obtain the list of published workflows and store it in memory when started 4. If the workflows in the Workspace change, you can use the `refresh_workflows` tool to refresh the cache 5. Only published workflows will be loaded into the service 6. The workflow execution timeout is 10 minutes, it is recommended to control the execution time within 5 minutes 7. You can view the detailed process of workflow execution through the returned `debug_url` ## Reference Documentation - [MCP Official Documentation](https://modelcontextprotocol.io/) - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Query Workflow List](https://www.coze.cn/open/docs/developer_guides/get_workflow_list) - [Execute Workflow](https://www.coze.cn/open/docs/developer_guides/workflow_run)