Mixpeek

Give your agent eyes. Search video, images, and audio via the Mixpeek multimodal retrieval API.

Open source Open in the app JSON README (API)

About

Give your agent eyes. Search video, images, and audio via the Mixpeek multimodal retrieval API.

Details

Kind: MCP servers
Topic: No topic detected
Publisher: mixpeek
Origin: official
Category: ferramentas
Transport: local
Version: 0.1.1
Stars: 1
Last push: 2026-04-16T20:29:50Z
Repository state: ativo
Language: Python
License: MIT
Added: 2026-08-29 04:00:50
Updated: 2026-08-29 04:00:50
Origin id: io.github.mixpeek/mcp-server

README

<p align="center">
  <img src="assets/header.png" alt="Mixpeek MCP Server" width="800" />
</p>

<!-- mcp-name: io.github.mixpeek/mcp-server -->

## Mixpeek MCP Server

A lightweight, production-friendly Model Context Protocol (MCP) server for Mixpeek that:

- Auto-loads Mixpeek's OpenAPI spec and exposes endpoints as MCP tools
- Supports local and hosted use (bring-your-own API key)
- Injects `Authorization` and `X-Namespace` headers
- Includes rate limits, timeouts, and redacted logs
- Ships with Docker and simple configuration

### Quickstart

1) Install

Python (PyPI):
```bash
# global (recommended)
pipx install mixpeek-mcp

# or in a venv
python -m venv .venv && source .venv/bin/activate
pip install mixpeek-mcp
```

npm (Node):
```bash
# run once
npx @mixpeek/mcp

# or install globally
npm i -g @mixpeek/mcp
```

Homebrew (macOS):
```bash
# tap and install (once the tap is live)
brew tap mixpeek/tap https://github.com/mixpeek/homebrew-tap
brew install mixpeek-mcp

# temporary local formula (dev/testing):
brew install --build-from-source Formula/mixpeek-mcp.rb
```

2) Configure (env or your MCP client secret store)

```bash
cp env.sample .env
# edit as needed
```

Env vars:

- `MIXPEEK_API_KEY`: Your Mixpeek API key (optional if endpoints don't require auth)
- `MIXPEEK_API_BASE`: Default `https://api.mixpeek.com`
- `MIXPEEK_OPENAPI_URL`: Defaults to `<API_BASE>/openapi.json` (or `/docs/openapi.json`)
- `MIXPEEK_NAMESPACE`: Optional namespace value to send via `X-Namespace`
- `MCP_RATE_MAX_CALLS`: Default `20` per `MCP_RATE_PER_SECONDS`
- `MCP_RATE_PER_SECONDS`: Default `10`
- `MCP_CONNECT_TIMEOUT`: Default `5`
- `MCP_READ_TIMEOUT`: Default `30`

3) Run locally (stdio)

```bash
# PyPI
mixpeek-mcp

# from source
python server.py

# npm
mixpeek-mcp
```

Your MCP client (e.g., Claude Desktop) can attach to this server via stdio.

### Docker

```bash
docker build -t mixpeek-mcp:latest .
docker run --rm -it \
  -e MIXPEEK_API_KEY=sk_... \
  -e MIXPEEK_NAMESPACE=your_namespace \
  mixpeek-mcp:latest
```

Or pull and run (once published):
```bash
docker run --rm -it \
  -e MIXPEEK_API_KEY=sk_... \
  -e MIXPEEK_NAMESPACE=your_namespace \
  ghcr.io/mixpeek/mcp:latest
```

### Distribution

- npm: `@mixpeek/mcp` → `https://www.npmjs.com/package/@mixpeek/mcp`
- PyPI: `mixpeek-mcp` → `https://pypi.org/project/mixpeek-mcp/` (publish pending)
- Docker Hub: `mixpeek/mcp` (pending push), GHCR: `ghcr.io/mixpeek/mcp` (pending push)
- Homebrew: `mixpeek/tap/mixpeek-mcp` (tap repo to be created)

### Submit to Docker MCP Registry

We prepared `registry.json` compatible with the [Official Docker MCP Registry](https://github.com/docker/mcp-registry/tree/main). To submit:

1) Fork the registry and create a new entry under the appropriate directory per their CONTRIBUTING guide.
2) Include our `registry.json` (update Docker image reference if you publish under a different org/tag).
3) Open a PR. Upon approval, it will appear in the MCP catalog and Docker Desktop's MCP Toolkit.

### Configuration

Required for write-protected endpoints:
- `MIXPEEK_API_KEY`: `Authorization: Bearer <key>`

Optional:
- `MIXPEEK_NAMESPACE`: sets `X-Namespace` for isolation
- `MIXPEEK_API_BASE`: defaults to `https://api.mixpeek.com`; testing: `https://server-xb24.onrender.com`
- `MIXPEEK_OPENAPI_URL`: defaults to `<API_BASE>/openapi.json` (or `/docs/openapi.json`)
- `MCP_RATE_MAX_CALLS` / `MCP_RATE_PER_SECONDS`: simple token bucket
- `MCP_CONNECT_TIMEOUT` / `MCP_READ_TIMEOUT`: request timeouts

### How it works

- Loads OpenAPI spec and maps GET/POST JSON endpoints to tools using `operationId`
- Tool arguments accept top-level query parameters or a `query`/`body` envelope
- Forwards requests to Mixpeek with configured headers
- Provides small allowlist (configurable) and redacts secrets in logs

### Testing

Unit tests:
```bash
pip install -r requirements.txt
pytest -q
```

Live test (optional):
```bash
export LIVE_MIXPEEK_API_KEY=sk_...
export LIVE_MIXPEEK_OPENAPI_URL=https://server-xb24.onrender.com/docs/openapi.json
export LIVE_MIXPEEK_API_BASE=https://server-xb24.onrender.com
pytest -q tests/test_live_integration.py
```

### Using with MCP clients

- This server uses MCP stdio transport and the official server interface, compatible with common MCP clients.
- Start the server, then point your MCP client to the stdio command (`mixpeek-mcp`).

### References

- Mixpeek docs: `https://docs.mixpeek.com/overview/introduction`
- Mixpeek OpenAPI: `https://api.mixpeek.com/docs/openapi.json`
 - MCP overview: `https://modelcontextprotocol.io/docs/getting-started/intro`

### Notes

- For production hosting, front with HTTPS, add SSO/session issuance, per-tenant rate limits, and audit logs without bodies/headers. Keep local stdio as the default; hosted HTTP/SSE can be added later.

Mixpeek

About

Details

README

More