This project is a Model Context Protocol (MCP) server that acts as a bridge to the Tuba.ai platform.
Tuba is an all-in-one AI vision workflow builder that streamlines the entire lifecycle of computer vision tasks. This server exposes your Tuba project's workflow as a set of callable tools, allowing other applications (like AI assistants, scripts, or services like Claude Desktop) to programmatically control and interact with your AI vision pipelines.
This MCP server provides the following tools to interact with the Tuba Workflow API:
| Tool | Description |
|---|---|
| run() | Executes the workflow for your project |
| status() | Retrieves the current workflow execution status |
| result() | Fetches workflow results (downloads as result.zip if file output) |
| get_workflow_blocks() | Retrieves the current configuration of all workflow blocks |
| update_workflow_blocks_data() | Updates parameters and uploads files to workflow blocks |
- Python 3.10 or higher - Required for modern type hints and async features
- uv - Fast Python package installer and environment manager
- A Tuba.ai account with an active project
- TUBA_WORKFLOW_ACCESS_TOKEN - Your project's API access token
-
Clone the repository:
git clone <this_repo> cd <this_repo>
-
Install uv:
-
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh -
Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-
-
Create a virtual environment and install dependencies:
uv venv uv pip install -r requirements-lock.txt
For local development, the server loads your access token from an environment file using python-dotenv.
-
Create a
.envfile in the project root:touch .env
-
Add your access token:
TUBA_WORKFLOW_ACCESS_TOKEN="your_secret_token_goes_here"
Note: The
.gitignorefile ensures this file is never committed to version control. -
Test the server:
uv run python tuba_workflow_mcp_server.py
-
Verify it's working: The server should start without errors. You can test it by connecting an MCP client or using the tools through Claude Desktop.
To use this server with Claude Desktop, add the following configuration to your claude_desktop_config.json file:
macOS/Linux Location:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows Location:
%APPDATA%\Claude\claude_desktop_config.json
Configuration:
{
"mcpServers": {
"TubaWorkflow": {
"command": "<home_path>/.local/bin/uv",
"args": [
"run",
"--directory",
"<absolute_path_to_tuba_workflow_mcp_server_folder>",
"python",
"tuba_workflow_mcp_server.py"
],
"env": {
"TUBA_WORKFLOW_ACCESS_TOKEN": "<your_access_token>"
}
}
}
}Replace the placeholders:
<home_path>- Your home directory path (e.g.,/Users/yournameorC:\Users\yourname)<absolute_path_to_tuba_workflow_mcp_server_folder>- Full path to this project folder<your_access_token>- Your Tuba.ai workflow access token
Example (macOS):
{
"mcpServers": {
"TubaWorkflow": {
"command": "/Users/john/.local/bin/uv",
"args": [
"run",
"--directory",
"/Users/john/projects/tuba-workflow-mcp-server",
"python",
"tuba_workflow_mcp_server.py"
],
"env": {
"TUBA_WORKFLOW_ACCESS_TOKEN": "<your_access_token>"
}
}
}
}After configuration, restart Claude Desktop to load the MCP server.
Executes the workflow for your authenticated project.
Retrieves the current status of the workflow execution.
Fetches the results of the workflow execution. If the result is a file (e.g., processed images, videos), it will be automatically saved as result.zip in your current working directory.
Retrieves the current configuration of all workflow blocks in your project. Use this to discover available block IDs and their current parameter values.
Updates parameters and uploads files to workflow blocks. Supports three file upload methods:
- Local files - Upload from file paths on your system
- Remote URLs - Fetch and upload files from web URLs
- Base64 data - Upload files encoded as base64 strings
File Field Naming Convention:
File field names should follow this format: <block_id>_<param_name>
Once configured with Claude Desktop (or another MCP client), you can interact with your Tuba workflow using natural language. The AI assistant will handle all the technical details like finding block IDs, formatting JSON correctly, handling file paths, and monitoring workflow progress.
Example conversations:
- "Can you check the status of my Tuba workflow?"
- "Start my workflow and let me know when it's done"
- "Update the confidence threshold to 0.8 for my object detector"
- "Process this image with my workflow: /path/to/image.jpg"
- "Upload these three images from URLs and run the workflow"
- "Show me my workflow configuration"
We welcome contributions! Please see our Code of Conduct for community guidelines.
Before contributing:
- Check existing issues and pull requests
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
For major changes, please open an issue first to discuss what you would like to change.
This project is licensed under the MIT License - see the LICENSE file for details.
Security is a top priority. If you discover a vulnerability, please report it responsibly.
Do not open public GitHub issues for security vulnerabilities.
Instead, use GitHub's private vulnerability reporting feature:
- Navigate to the Security tab
- Click Report a Vulnerability
- Provide detailed information about the issue
See SECURITY.md for more information.
For questions, issues, or feedback:
- Tuba.ai Support: support@tuba.ai
- Join Discord Community https://discord.com/invite/gDSZr6N5rC
- GitHub Issues: Use for bug reports and feature requests
- Discussions: Use GitHub Discussions for questions and community interaction
Copyright © 2025 DevisionX. All rights reserved.