mcp-toolbox

A comprehensive toolkit for enhancing LLM capabilities through the Model Context Protocol (MCP). This package provides a collection of tools that allow LLMs to interact with external services and APIs, extending their functionality beyond text generation.

• GitHub repository:
• (WIP)Documentation:

Features

> \*nix is our main target, but Windows should work too.

• Command Line Execution: Execute any command line instruction through LLM
• Figma Integration: Access Figma files, components, styles, and more
• Extensible Architecture: Easily add new API integrations
• MCP Protocol Support: Compatible with Claude Desktop and other MCP-enabled LLMs
• Comprehensive Testing: Well-tested codebase with high test coverage

Installation

Using uv (Recommended)

We recommend using uv to manage your environment.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # For macOS/Linux
# or
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # For Windows

Then you can use `uvx "mcp-toolbox@latest" stdio` as commands for running the MCP server for latest version. Audio and memory tools are not included in the default installation., you can include them by installing the `all` extra:

> [audio] for audio tools, [memory] for memory tools, [all] for all tools

uvx "mcp-toolbox[all]@latest" stdio

Installing via Smithery

To install Toolbox for LLM Enhancement for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ai-zerolab/mcp-toolbox --client claude

Using pip

pip install "mcp-toolbox[all]"

And you can use `mcp-toolbox stdio` as commands for running the MCP server.

Configuration

Environment Variables

The following environment variables can be configured:

• `FIGMA_API_KEY`: API key for Figma integration
• `TAVILY_API_KEY`: API key for Tavily integration
• `DUCKDUCKGO_API_KEY`: API key for DuckDuckGo integration
• `BFL_API_KEY`: API key for Flux image generation API

Memory Storage

Memory tools store data in the following locations:

• macOS: `~/Documents/zerolab/mcp-toolbox/memory` (syncs across devices via iCloud)
• Other platforms: `~/.zerolab/mcp-toolbox/memory`

Full Configuration

To use mcp-toolbox with Claude Desktop/Cline/Cursor/..., add the following to your configuration file:

{
  "mcpServers": {
    "zerolab-toolbox": {
      "command": "uvx",
      "args": ["--prerelease=allow", "mcp-toolbox@latest", "stdio"],
      "env": {
        "FIGMA_API_KEY": "your-figma-api-key",
        "TAVILY_API_KEY": "your-tavily-api-key",
        "DUCKDUCKGO_API_KEY": "your-duckduckgo-api-key",
        "BFL_API_KEY": "your-bfl-api-key"
      }
    }
  }
}

For full features:

{
  "mcpServers": {
    "zerolab-toolbox": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "--python=3.12",
        "mcp-toolbox[all]@latest",
        "stdio"
      ],
      "env": {
        "FIGMA_API_KEY": "your-figma-api-key",
        "TAVILY_API_KEY": "your-tavily-api-key",
        "DUCKDUCKGO_API_KEY": "your-duckduckgo-api-key",
        "BFL_API_KEY": "your-bfl-api-key"
      }
    }
  }
}

You can generate a debug configuration template using:

uv run generate_config_template.py

Available Tools

Command Line Tools

File Operations Tools

Figma Tools

XiaoyuZhouFM Tools

Audio Tools

Memory Tools

Markitdown Tools

Web Tools

Flux Image Generation Tools

Usage Examples

Running the MCP Server

# Run with stdio transport (default)
mcp-toolbox stdio

# Run with SSE transport
mcp-toolbox sse --host localhost --port 9871

Using with Claude Desktop

1. Configure Claude Desktop as shown in the Configuration section

1. Start Claude Desktop

1. Ask Claude to interact with Figma files:

1. Ask Claude to execute command line instructions:

1. Ask Claude to download podcasts from XiaoyuZhouFM:

1. Ask Claude to work with audio files:

1. Ask Claude to convert files or URLs to Markdown:

1. Ask Claude to work with web content:

1. Ask Claude to generate images with Flux:

1. Ask Claude to use memory tools:

Development

Local Setup

Fork the repository and clone it to your local machine.

# Install in development mode
make install
# Activate a virtual environment
source .venv/bin/activate  # For macOS/Linux
# or
.venv\Scripts\activate  # For Windows

Running Tests

make test

Running Checks

make check

Building Documentation

make docs

Adding New Tools

To add a new API integration:

1. Update `config.py` with any required API keys

1. Create a new module in `mcp_toolbox/`

1. Implement your API client and tools

1. Add tests for your new functionality

1. Update the README.md with new environment variables and tools

See the development guide for more detailed instructions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

1. Create a feature branch (`git checkout -b feature/amazing-feature`)

1. Commit your changes (`git commit -m 'Add some amazing feature'`)

1. Push to the branch (`git push origin feature/amazing-feature`)

1. Open a Pull Request

License

This project is licensed under the terms of the license included in the repository.