ObjectStore MCP

Multi-Backend Object Storage | MCP Server

The object-storage connector for the agent-utilities fleet: one MCP tool surface over S3 and S3-compatible stores (MinIO, Cloudflare R2), Google Cloud Storage, Azure Blob Storage, and a zero-infra local-filesystem backend.

Version: 0.3.0

Documentation — Installation, deployment, and usage across the API, CLI, and MCP interfaces are maintained in docs/.

Table of Contents

• Overview
• What it provides
• Backend × capability matrix
• Installation
• Configuration (environment)
• Usage
• MCP config
• Docker deployment
• Development
• License

Overview

objectstore-mcp wraps heterogeneous object stores behind one typed, deterministic MCP tool surface, plus an optional Pydantic-AI A2A agent server (objectstore-agent). Safety caps, explicit buckets, and dry-run-by-default batch deletes are enforced uniformly in the tool layer, regardless of backend.

What it provides

• A multi-backend store abstraction (objectstore_mcp.api, CONCEPT:OBJ-1.0) — every provider implements the same ObjectStoreBackend protocol, validated by a single conformance test suite that runs for real against the filesystem backend.

• Three consolidated, action-routed MCP tools (objectstore-mcp console script):

  Tool	Actions	Description
  objects	list (prefix/delimiter pagination), head, get (text/base64, size-capped), put (text/base64, size-capped), copy, move, delete, delete_batch (capped, dry-run by default), presign, metadata_get, metadata_set	Single-object lifecycle and listing on any store
  buckets	list, create, delete (empty-only, opt-in), exists, info, stores	Bucket/container admin and store registry introspection
  transfer	upload, download, upload_dir, download_prefix (all size/batch-capped)	Local-filesystem ⇄ object-store transfer, single or by prefix

  The whole tool set toggles with OBJECTSTORETOOL.

• Named multi-store routing — OBJECTSTORE_STORES JSON maps store names to {backend, bucket?, endpoint?, profile?, ...}; every tool takes an optional store argument. A zero-infra local filesystem store always exists, so the server works with no cloud credentials at all.

• A safety governor — size caps on get/put/transfer, list/batch key caps, deletes that demand an explicit bucket+key (no wildcards), batch deletes that are prefix-scoped, capped, and dry-run by default, and bucket deletes that are empty-only and disabled unless explicitly enabled.

Backend × capability matrix

Installation

pip install objectstore-mcp            # core: local filesystem backend only
pip install objectstore-mcp[s3]        # + boto3 (S3, MinIO, R2)
pip install objectstore-mcp[gcs]       # + google-cloud-storage
pip install objectstore-mcp[azure]     # + azure-storage-blob
pip install objectstore-mcp[all]       # everything (incl. MCP + agent extras)

Or pull the container image:

docker pull knucklessg1/objectstore-mcp:latest

Configuration (environment)

Provider credentials resolve through each SDK's own chain — boto3's resolution order for S3 (env keys, ~/.aws profiles via the store's profile, SSO, instance metadata), GOOGLE_APPLICATION_CREDENTIALS / Application Default Credentials for GCS, and AZURE_STORAGE_CONNECTION_STRING for Azure Blob.

Example store registry

{
  "media":   {"backend": "s3", "bucket": "media-prod", "profile": "prod", "region": "us-east-1"},
  "minio":   {"backend": "s3", "endpoint": "http://minio.arpa:9000"},
  "r2":      {"backend": "s3", "endpoint": "https://<account>.r2.cloudflarestorage.com"},
  "reports": {"backend": "gcs", "bucket": "acme-reports"},
  "archive": {"backend": "azure", "bucket": "archive"},
  "scratch": {"backend": "filesystem", "root": "~/scratch-store"}
}

Usage

objectstore-mcp                                   # stdio
objectstore-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Example tool calls (any MCP client):

// Write then read a text object on the zero-infra local store
{"tool": "buckets",  "arguments": {"action": "create", "params_json": "{\"bucket\": \"notes\"}"}}
{"tool": "objects",  "arguments": {"action": "put",    "params_json": "{\"bucket\": \"notes\", \"key\": \"todo.md\", \"text\": \"- ship it\"}"}}
{"tool": "objects",  "arguments": {"action": "get",    "params_json": "{\"bucket\": \"notes\", \"key\": \"todo.md\"}"}}

// Preview then execute a prefix-scoped batch delete on a named S3 store
{"tool": "objects", "arguments": {"store": "media", "action": "delete_batch", "params_json": "{\"bucket\": \"media-prod\", \"prefix\": \"tmp/\"}"}}
{"tool": "objects", "arguments": {"store": "media", "action": "delete_batch", "params_json": "{\"bucket\": \"media-prod\", \"prefix\": \"tmp/\", \"dry_run\": false}"}}

MCP config

{
  "mcpServers": {
    "objectstore-mcp": {
      "command": "uv",
      "args": ["run", "objectstore-mcp"],
      "env": {
        "OBJECTSTORE_STORES": "{\"minio\": {\"backend\": \"s3\", \"endpoint\": \"http://minio.arpa:9000\"}}",
        "OBJECTSTORE_DEFAULT_STORE": "local"
      }
    }
  }
}

Run the A2A agent server against a live MCP server:

objectstore-agent --mcp-url http://localhost:8000/mcp --host 0.0.0.0 --port 9001

Additional Deployment Options

objectstore-mcp can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

• Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
• Remote URL — connect to a server deployed behind Caddy at http://objectstore-mcp.arpa/mcp using the "url" key.

Docker deployment

docker compose -f docker/mcp.compose.yml up -d      # MCP server only
docker compose -f docker/agent.compose.yml up -d    # MCP + A2A agent
curl -s http://localhost:8000/health                 # {"status":"OK"}

Both services read configuration from ../.env (copy .env.example); see docs/deployment.md.

Development

pip install -e .[test]
pytest                       # full suite (cloud SDKs not required)
pip install -e .[test-s3]    # adds boto3+moto integration tests
pre-commit run --all-files

See docs/ for architecture, concepts, and deployment details.

License

MIT — see LICENSE.