Carrot MCP

A collection of MCP (Model Context Protocol) servers for various hardware and data interfaces.

Installation

uvx (no install, always latest)

Run directly without installing. Always fetches latest version.

# Run any server directly
uvx carrot-mcp-pdf@latest
uvx carrot-mcp-io@latest
uvx carrot-mcp-nfc@latest
uvx carrot-mcp-office@latest
uvx carrot-mcp-sys@latest

# Run via meta package
uvx carrot-mcp run pdf

uv tool (recommended)

Persistent install with automatic PATH setup. Upgrades cleanly.

# Install all
uv tool install carrot-mcp

# Install specific servers
uv tool install carrot-mcp[pdf]
uv tool install carrot-mcp[io]
uv tool install carrot-mcp[nfc]
uv tool install carrot-mcp[office]
uv tool install carrot-mcp[sys]

# Or install sub-packages directly
uv tool install carrot-mcp-pdf
uv tool install carrot-mcp-io
uv tool install carrot-mcp-nfc
uv tool install carrot-mcp-office
uv tool install carrot-mcp-sys

# Upgrade
uv tool upgrade carrot-mcp

# Uninstall
uv tool uninstall carrot-mcp

pip

Classic Python install. Requires manual PATH setup.

# Install all
pip install carrot-mcp

# Install specific servers
pip install carrot-mcp[pdf]
pip install carrot-mcp[io]
pip install carrot-mcp[nfc]
pip install carrot-mcp[office]
pip install carrot-mcp[sys]

# Or install sub-packages directly
pip install carrot-mcp-pdf
pip install carrot-mcp-io
pip install carrot-mcp-nfc
pip install carrot-mcp-office
pip install carrot-mcp-sys

# Upgrade
pip install --upgrade carrot-mcp

# Uninstall
pip uninstall carrot-mcp

Quick Start

uvx (no install, always latest)

# Run a specific server directly
uvx carrot-mcp-pdf@latest
uvx carrot-mcp-io@latest
uvx carrot-mcp-nfc@latest
uvx carrot-mcp-office@latest
uvx carrot-mcp-sys@latest

# List available servers
uvx carrot-mcp list

# Add all carrot servers to supported agents
uvx carrot-mcp mcp add

# Force uvx mode for agent configs
uvx carrot-mcp mcp add --uvx

# Force local mode
uvx carrot-mcp mcp add --local

# Remove all carrot servers from agents
uvx carrot-mcp mcp remove

CLI (after uv tool or pip install)

# List all available servers
carrot-mcp list

# Run a specific server
carrot-mcp run pdf
carrot-mcp run io
carrot-mcp run nfc
carrot-mcp run office
carrot-mcp run sys

# Add all carrot servers to supported agents
carrot-mcp mcp add

# Add to specific agent(s)
carrot-mcp mcp add gemini
carrot-mcp mcp add claude mimocode opencode gemini

# Force uvx mode (auto-update)
carrot-mcp mcp add --uvx

# Force local mode
carrot-mcp mcp add --local

# Remove all carrot servers from agents
carrot-mcp mcp remove

# Remove from specific agent(s)
carrot-mcp mcp remove claude

# Run with uv
uv run carrot-mcp run office

Python module

python -m carrot_mcp_pdf
python -m carrot_mcp_io
python -m carrot_mcp_nfc
python -m carrot_mcp_office
python -m carrot_mcp_sys

Available Servers

Document Servers

PDF MCP Tools

Environment variables:

Office MCP Tools

Excel Tools

Word Tools

Backup Tools

Features:

• Auto-backup: All modifications are automatically versioned
• Legacy format support: .doc → .docx, .xls → .xlsx via win32com (Windows)
• 100 version limit with 14-day expiry per file

Environment variables:

Hardware Servers

IO MCP Tools

NFC MCP Tools

System MCP Tools

MCP Configuration

Auto-config (recommended)

carrot-mcp mcp add

This adds all servers to supported agents (claude, opencode, mimocode). Auto-detects whether to use carrot-mcp run or uvx based on what's installed. Use --uvx or --local to override.

Manual config

Claude Desktop (~/.claude.json):

{
  "mcpServers": {
    "carrot-pdf": {
      "command": "carrot-mcp",
      "args": ["run", "pdf"]
    },
    "carrot-office": {
      "command": "carrot-mcp",
      "args": ["run", "office"]
    },
    "carrot-io": {
      "command": "carrot-mcp",
      "args": ["run", "io"]
    },
    "carrot-nfc": {
      "command": "carrot-mcp",
      "args": ["run", "nfc"]
    },
    "carrot-sys": {
      "command": "carrot-mcp",
      "args": ["run", "sys"]
    }
  }
}

OpenCode / MiMoCode (~/.config/opencode/opencode.jsonc or ~/.config/mimocode/mimocode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "carrot-pdf": {
      "type": "local",
      "command": ["carrot-mcp", "run", "pdf"],
      "enabled": true,
      "environment": {}
    },
    "carrot-office": {
      "type": "local",
      "command": ["carrot-mcp", "run", "office"],
      "enabled": true,
      "environment": {}
    },
    "carrot-io": {
      "type": "local",
      "command": ["carrot-mcp", "run", "io"],
      "enabled": true,
      "environment": {}
    },
    "carrot-nfc": {
      "type": "local",
      "command": ["carrot-mcp", "run", "nfc"],
      "enabled": true,
      "environment": {}
    },
    "carrot-sys": {
      "type": "local",
      "command": ["carrot-mcp", "run", "sys"],
      "enabled": true,
      "environment": {}
    }
  }
}

Development

# Clone and setup
git clone <repo-url>
cd carrot-mcp
uv sync --all-packages

# Run tests
uv run pytest

# Run tests for specific server
uv run pytest tests/pdf/ -v
uv run pytest tests/office/ -v
uv run pytest tests/io/ -v
uv run pytest tests/nfc/ -v
uv run pytest tests/sys/ -v

# Bump version and release
bump.bat                        # interactive
bump.bat carrot-mcp-office      # direct package

License

Apache License 2.0 - see LICENSE for details.