Skip to main content
Glama
shgsousa

blob-storage

by shgsousa
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Blob Storage Service

A lightweight MCP data broker that stores large binary payloads under a UUID, enabling MCP clients and agents to exchange massive results without flooding the LLM context window.

Architecture

MCP Client / LLM Agent
        │
        │  tool call (large result)
        ▼
   MCP Server  ──store_blob──▶  Blob Storage Service  ──▶  SQLite + local files
        │                              │
        │  returns UUID                │  retrieve_blob(uuid)
        ◀──────────────────────────────┘

The agent only ever sees a UUID token — not the raw bytes.

Related MCP server: memex

Project Structure

src/blob_storage/
├── __init__.py       # package metadata
├── config.py         # pydantic-settings (env / .env)
├── models.py         # SQLAlchemy ORM + Pydantic schemas
├── database.py       # async engine, session factory, init_db()
├── storage.py        # StorageBackend ABC + LocalFileBackend
├── service.py        # BlobService (orchestration)
├── api.py            # FastAPI REST API
└── mcp_server.py     # MCP server (HTTP Streamable, /mcp)

tests/
├── conftest.py       # shared fixtures
├── test_api.py       # API integration tests
└── test_service.py   # service unit tests

Quickstart

Install dependencies

uv sync

Start the REST API

uv run blob-api                            # defaults from config / .env
uv run blob-api --host 0.0.0.0 --port 9000 # override at runtime

Interactive docs available at http://<host>:<port>/docs.

Start the MCP server

uv run blob-mcp                            # defaults: 0.0.0.0:8001
uv run blob-mcp --host 0.0.0.0 --port 9001

The MCP endpoint is served at http://<host>:<port>/mcp.

Configuration

Settings are read from environment variables or a .env file in the project root.

Variable

Default

Description

STORAGE_DIR

./data/blobs

Directory for blob files

DATABASE_URL

sqlite+aiosqlite:///./data/metadata.db

SQLAlchemy async DB URL

DEFAULT_TTL_SECONDS

7776000

Default TTL — 90 days. Use 0 for no expiry.

MAX_BLOB_SIZE_BYTES

524288000

Max upload size (500 MB)

API_HOST

0.0.0.0

REST API bind address

API_PORT

8000

REST API port

MCP_HOST

0.0.0.0

MCP server bind address

MCP_PORT

8001

MCP server port

MCP_API_BASE_URL

http://127.0.0.1:8000

REST API URL used internally by the MCP server

SWEEP_INTERVAL_SECONDS

3600

How often the TTL cleanup job runs

CLI flags (--host, --port) take precedence over config/env for the respective server.

REST API Reference

Method

Path

Description

GET

/health

Liveness check

POST

/blobs

Store a blob

GET

/blobs/{uuid}

Download a blob

GET

/blobs/{uuid}/meta

Metadata only (no payload)

DELETE

/blobs/{uuid}

Delete a blob

Store a blob

Pass metadata as custom request headers:

Header

Default

Description

X-Mime-Type

application/octet-stream

MIME type of the payload

X-Ttl-Seconds

config default

Override TTL; 0 = never expires

X-Origin

—

Free-form source identifier

X-Tags

—

JSON object for arbitrary labels

curl -X POST http://localhost:8000/blobs \
  -H "Content-Type: application/octet-stream" \
  -H "X-Mime-Type: application/json" \
  -H "X-Origin: my-mcp-server" \
  --data-binary '{"key": "value"}'

Response:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "expires_at": "2026-05-30T16:42:07Z",
  "size_bytes": 16
}

MCP Integration

The MCP server uses the Streamable HTTP transport. Configure your MCP host to connect over HTTP rather than spawning a subprocess:

{
  "mcpServers": {
    "blob-storage": {
      "type": "http",
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

Available tools

Tool

Input

Output

store_blob

data_b64, mime_type, ttl_seconds?, origin?, tags?

{ uuid, expires_at, size_bytes }

retrieve_blob

uuid

{ uuid, mime_type, data_b64 }

get_blob_meta

uuid

metadata JSON

delete_blob

uuid

{ deleted: uuid }

All binary data is base64-encoded in MCP tool calls (MCP messages are JSON/text).

Running Tests

uv run pytest tests/ -v

Extending the Storage Backend

To use S3 or MinIO in production, implement the StorageBackend abstract class in storage.py:

from blob_storage.storage import StorageBackend

class S3Backend(StorageBackend):
    async def store(self, blob_uuid: str, data: bytes) -> None: ...
    async def retrieve(self, blob_uuid: str) -> bytes: ...
    async def delete(self, blob_uuid: str) -> None: ...

Then inject it into BlobService and the _backend singleton in api.py.

This server cannot be installed

F
license - not found
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shgsousa/blob-storage'

If you have feedback or need assistance with the MCP directory API, please join our Discord server