MCP Toolbox: A "BusyBox" for Your LLM

A versatile, containerized server that provides a collection of essential utility tools for LLM clients, all accessible via the Model Context Protocol (MCP). This project is designed to be a simple, easy-to-deploy "swiss army knife" for your AI agents.

---

For Humans 👋

This guide is for developers who want to quickly deploy and use a powerful set of pre-built tools with their MCP-compatible LLM client (like Cline).

Features

• All-in-One: A single, easy-to-deploy container with a wide range of common utilities.
• Lightweight: Built on Node.js and Alpine Linux for a small footprint.
• Extensible: Designed to be easily extended with new tools.
• Comprehensive Toolset: Includes tools for basic utilities, data manipulation, and web interaction.

Getting Started

Production (Published Image)

1. Prerequisites: You'll need Docker installed.
2. Run the Server: You can run the server directly from the published Docker image.

   docker run -d \
     -p 8049:8049 \
     -e GOOGLE_API_KEY="YOUR_API_KEY" \
     -e GOOGLE_CX="YOUR_SEARCH_ENGINE_ID" \
     ghcr.io/phippsy22/mcp-toolbox:latest
   

Local Development (Building from Source)

1. Prerequisites: You'll need Docker and Docker Compose installed.

2. Configuration:

   • This project uses a local .env file for API keys. An example file is provided.
   • Copy the example environment file to create your local configuration:

     cp .env.example .env
     

   • Open the new .env file and add your Google Custom Search credentials. The server will run without these keys, but the web_search tool will not be functional.

3. Build and Run the Server: Use Docker Compose to build and run the container. This will use the docker-compose.yml file in this directory.

   docker compose up --build
   

   The server will be available at http://localhost:8050.

4. Connect Your Client: Configure your MCP client to connect to the server.

   • For the production image, use port 8049.
   • For local development, use port 8050.

   An example cline_mcp_settings.json entry for local development would look like this:

   {
     "mcpServers": {
       "toolbox-mcp-local": {
         "autoApprove": [],
         "disabled": false,
         "timeout": 360,
         "type": "sse",
         "url": "http://localhost:8050/mcp"
       }
     }
   }
   

   Note that the type is explicitly set to "sse" for compatibility with the current Cline client.

---

For Robots (and Power Users) 🤖

This section provides the technical details for programmatic interaction and customization.

Docker Image

• Registry: ghcr.io
• Image: ghcr.io/phippsy22/mcp-toolbox:latest

Service Endpoint

• URL: http://localhost:8049/mcp
• Transport: sse (Server-Sent Events)

Tool Manifest

• echo: A simple tool that returns the text it was given.
  • Parameters: text (string)
• time: Returns the current server time, optionally in a specific timezone.
  • Parameters: timezone (string, optional)
• random: Generates random data such as UUIDs, strings, or numbers.
  • Parameters: type (enum: "uuid", "string", "number", optional, default: "uuid"), length (number, optional, default: 16), min (number, optional, default: 0), max (number, optional, default: 1)
• encoder: Encodes a string using a specified format (base64 or url).
  • Parameters: text (string), format (enum: "base64", "url")
• decoder: Decodes a string from a specified format (base64 or url).
  • Parameters: text (string), format (enum: "base64", "url")
• calculator: Evaluates a mathematical expression.
  • Parameters: expression (string)
• web_fetch: Fetches content from a specified URL and converts it to a specified format.
  • Parameters: url (string), format (enum: "text", "markdown", "json", optional, default: "text")
• system_info: Provides information about the system environment.
  • Parameters: None
• web_search: Performs a web search using Google Custom Search.
  • Parameters: query (string), format (enum: "json", "markdown", optional, default: "json")