base64_server

This MCP server provides simple Base64 encoding and decoding capabilities for both text and images. It supports text-to-base64 encoding and decoding, image-to-base64 encoding, and decoding Base64 data back into an image with a configurable MIME type. It also recognizes and handles Data URLs, making it convenient to work with embedded data in web contexts. The server exposes a set of tools and a minimal API that you can call via the MCP client to perform these conversions quickly.

To integrate with clients, you can configure the server in your MCP setup so that the MCP client can invoke the encode/decode tools directly. For example, you can access text encoding via a function like base64_encode_text(text) or decode via base64_decode_text(encoded). For images, use base64_encode_image(image_path) to generate a Base64 string, and base64_decode_image(encoded, output_path, mime_type) to save a decoded image to disk. The API also supports resources in encode:// and decode:// namespaces for programmatic access to encoded or decoded data, which helps streamline workflows in automation or scripting scenarios. Additionally, there are prompt templates like base64_usage_guide() and encode_text_prompt(...) to help guide user interactions with the service.

If you’re integrating with an MCP client, you can add a server entry that routes requests to the uv-based runner so that the client can call mcp run to execute the Python-based server script that implements these utilities. This makes it easy to embed Base64 services into larger MCP-powered workflows without extra dependencies on the client side.

Prerequisites:

• Python installed (for uv-based execution)
• uv (Python virtual environment manager) installed
• Access to install via npm (optional, for Smithery integration) if you plan to use Smithery tooling

1. Set up a Python virtual environment and install the package in development mode

# Create a virtual environment (using uv's guidance)
uv venv

# Activate the virtual environment
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# Install the package in development mode
uv pip install -e .

# If you need development dependencies, install them as well
uv pip install -e ".[dev]"

2. Install Smithery (optional, for easier CLI tooling integration with Claude desktop)

npx -y @smithery/cli install @liuyazui/base64_server --client claude

3. Run the MCP server via uv (as configured in the MCP config)

# Example run using the configured path to the base64_server.py script
uv run --with mcp[cli] mcp run [path to base64_server.py]

Notes:

• Ensure the path to base64_server.py in your MCP configuration points to the actual server script.
• If you are packaging for distribution, consider replacing [path to base64_server.py] with the correct module/script entry point.
• The installation steps assume a development workflow; for production, package installation and environment management should align with your deployment strategy.

Tips and common issues:

• If you see module or dependency errors, ensure your virtual environment is activated and that uv-managed Python dependencies are installed (uv pip install -e .).
• The server is designed to be invoked via the MCP client; ensure your MCP config uses the uv-based command and passes the correct path to the Python MCP server script.
• For image encoding/decoding, you may need to ensure the output MIME type is specified if your downstream apps require a specific format (default is image/png).
• Data URL handling is supported, so you can embed encoded data inline in HTML or JSON responses.
• If you plan to deploy in containers, you can adapt the uv-based command into a container entry point and expose the necessary port and environment variables.
• No environment variables are strictly required by default, but you can add placeholders for API keys or configuration flags if you extend the server functionality.