Podyx MCP

Русский · Client setup · Tools · Releases · Contributing · Agent instructions

Unofficial, local-first community MCP server for studio owners using Podyx. Connect your own studio key and ask an assistant about availability, bookings, clients, packages, prices and business performance.

150 API-backed tools: 65 reads/previews enabled by default and 85 opt-in mutations. Full v2 operations plus v1 reads and reports, without duplicate v1/headless routes. No Kommo dependency. Includes MCP prompts for a monthly review, finding a session time and preparing a booking change.

Podyx and API reference

• Podyx website

• Interactive API v2 reference

• OpenAPI v2 specification (JSON)

• Legacy API v1 specification (JSON), used for reports and legacy reads.

Related MCP server: dreambooth-mcp

Quick start

Requires Node.js 22+, npm and a Podyx studio key. Use a key with only the permissions you need. API access must be enabled for the studio; creating commercial entries may need additional Podyx enablement.

Download a client plugin from Releases once a release is published, or use this source checkout:

git clone https://github.com/Studio-Red-Barcelona/podyx-mcp.git
cd podyx-mcp
npm ci
mkdir -p ~/.config/podyx-mcp
cp .env.example ~/.config/podyx-mcp/.env
chmod 600 ~/.config/podyx-mcp/.env

Edit that private file: replace YOUR_PODYX_API_KEY with a key from Podyx → Settings → API keys. Leave PODYX_ENABLE_WRITES=false for initial use. Do not paste secrets into chat. PODYX_ENV_FILE can point to another private environment file; existing process environment values take precedence.

npm run configs

Merge the appropriate file from generated/ into your client's settings. They contain absolute local paths and no secret values. The client launches the server on demand. Running npm start manually waits for MCP input on stdin; this is normal.

Optional Docker distribution

Docker runs the same MCP without a local Node.js installation or source checkout. Release images support amd64/arm64, run as non-root and keep their journal in a volume. Both stdio clients and a private HTTP Compose deployment are supported. See Docker setup, deployment and updates. GHCR images become available after the first release containing this support.

Clients

See client setup. Local execution means the MCP process and studio key stay on your machine; selected tool results still go to the AI provider you use. Plugin ZIPs are installation artifacts, not published marketplace listings.

Examples

• “Find available two-hour slots next Saturday for this setup.”

• “Compare last month's revenue, capacity and customer activity with the previous month.”

• “Explain the surcharge in this booking quote.”

• “How many eligible sessions remain in this client's package?”

• With writes enabled: “Preview extending this session by one hour; show the difference before changing it.”

Tool reference lists every tool and route. Inputs use path, query and body containers matching Podyx. Responses retain upstream pagination and exact decimal amounts. Tools perform one API call per invocation; assistants must follow pagination rather than infer totals from one page.

Enable changes

Set PODYX_ENABLE_WRITES=true in the private environment file and restart/refresh the MCP connection. Podyx key permissions still apply. Every mutation also needs confirm: true and a UUID idempotency_key that the caller persists before submitting. Preview first where the API provides one; the assistant should obtain authorization for the actual change.

The server stores only an operation name and an argument hash for each request UUID, not the request body or customer data. Default location: ~/.local/state/podyx-mcp. It rejects reuse of a UUID with changed arguments. This local journal is scoped to the API origin and key; Podyx remains authoritative for replay and financial identities. A timeout is unknown, not proof of failure. See design and limitations.

HTTP mode

Generate a separate random token, for example with openssl rand -hex 32, and save it as PODYX_MCP_TOKEN in the private file. Then:

npm run start:http

The server listens only on 127.0.0.1:3333, uses Streamable HTTP at /mcp, and requires Authorization: Bearer <PODYX_MCP_TOKEN>. This token is distinct from the Podyx API key. Set PODYX_ALLOWED_HOSTS to exact hostnames if a reverse proxy preserves its public Host header. Browser Origin requests are rejected; this endpoint is for MCP clients and server-side bridges. Do not remove authentication to get a public tunnel working.

Build community plugin packages

npm run check
npm test
npm run package:plugins
npm run test:packages

dist/ contains complete Cursor, Claude Code and OpenAI plugin folders and ZIPs, including installed runtime dependencies. Node.js must still be installed. Packaging and archive smoke tests require the zip / unzip commands (available on macOS and most Linux development machines). Run packaging once into a fresh dist/; it refuses existing output directories. Source templates in plugins/ intentionally do not contain the runtime.

Repository marketplaces are included for Cursor, Claude Code and OpenAI; build packages before using them. Public directory submission, signing, OAuth hosting and account-side installation are separate from building a local package.

Automated releases

PRs and merges to main run tests on Node.js 22/24, enforce matching plugin versions and build/test all release archives. After successful main checks, Release Please opens a version/changelog PR. Merging that PR produces the GitHub tag and release with the tested archives. Configure the GitHub remote, allow Actions to create PRs, and set branch rules once; see release pipeline and required checks.

Development and status

npm ci
npm run check
npm test

Tests cover schema validation, safe defaults, request construction, error/redaction behavior, uncertain-write recovery, the local Grok bridge, real MCP stdio and real Streamable HTTP on loopback. Upstream behavior is mocked: live studio operations and client UIs require testing with your own key/account. No production studio data is bundled.

API snapshots were retrieved on 2026-11-05. Specs are vendored so startup needs no documentation download. Changes to upstream API contracts require review and a new release. MIT for original implementation; see NOTICE.md for upstream material.

The public repository is maintained by @d3rky. Changes use reviewed PRs with passing checks; see repository governance. This project is not affiliated with or endorsed by Podyx.