motionmcp

Python SDK for MMCP — the Motion Model Context Protocol.

Build a vendor-neutral motion-generation HTTP server in ~30 lines: the SDK handles wire-format validation, glTF encoding, and the standard error envelope; you implement model loading and a single generate() method.

Where this fits

MMCP is a small HTTP protocol; this is the Python SDK that makes implementing the server side trivial.

Officially supported servers (built on this SDK):

• motionmcp-kimodo — the Kimodo SOMA model. Open-source, self-hosted.
• Animatica Cloud — hosted product. Adds skeleton retargeting, managed GPUs, batch generation, multi-tenant auth.

Officially supported clients:

• Proscenium for Blender — directable motion generation in Blender 4.2+. Talks to any MMCP server.

Want to add another model or DCC? The protocol is yours to implement — this SDK just makes the server side easy. See Servers & clients for the full list and how to build your own.

from motionmcp import Backbone, ModelSpec, GenerateRequest, MotionResult, serve

class MyBackbone(Backbone):
    def capabilities(self) -> ModelSpec:
        return ModelSpec(
            id="my-model",
            fps=30.0,
            canonical_skeleton=load_skeleton(),
            supports_retargeting=False,
            supported_constraints=["pose_keyframe"],
        )

    async def generate(self, req: GenerateRequest) -> MotionResult:
        rotations    = self.model.run(req)        # (N, T, J, 4) (x,y,z,w)
        translations = self.model.run_root(req)   # (N, T, 3)
        return MotionResult(
            rotations=rotations,
            root_translations=translations,
        )

if __name__ == "__main__":
    serve(MyBackbone())

That's the whole server. Hit GET /capabilities to discover the model; POST /generate to run it. Returns standard glTF 2.0 — load it with any glTF parser.

Install

# server: implement a Backbone and serve it
pip install "motionmcp-sdk[server]"

# client / library only: talk to an MMCP server
pip install motionmcp-sdk

Since 0.6.0 the server stack (FastAPI, pydantic, uvicorn) is the [server] extra; up to 0.5.0 it was part of the base install.

Requires Python 3.9+.

What the SDK gives you

• Schemas: Pydantic models for the full wire format (Skeleton, Segment, Constraint, Options, GenerateRequest). Free validation, IDE autocomplete, OpenAPI docs at /docs.
• Endpoints: GET /capabilities, POST /generate, plus a generic exception → MMCP error envelope handler.
• Generic checks: unknown model, unknown joint in constraint, frame-out-of-range, retargeting policy, constraint count, prompt length, duration limit. All raise the right error.code.
• glTF encoder: numpy arrays in, glTF 2.0 JSON out, with the MMCP_motion extension correctly populated.
• Reference impl: NullBackbone returns a rest pose for any request. Useful for plugin development against a real server with zero ML deps.

What you implement

• Backbone.capabilities() -> ModelSpec — what model you serve.
• Backbone.generate(request) -> MotionResult — the actual generation. May be async def or sync.
• Backbone.setup() / teardown() — optional, for model loading and GPU allocation.

That's it.

Multi-model

Serve more than one model from one process:

serve({
    "fast":    FastBackbone(),
    "quality": QualityBackbone(),
})

Or pass an iterable; ids come from each backbone's capabilities().id.

NullBackbone — try it now

pip install motionmcp-sdk
python -m motionmcp.null_backbone
# → MMCP server on :8000, returning rest pose for any request

Client side

motionmcp.client is the other half of the SDK: a Python client for talking to any MMCP server, not just ones built with this package. It speaks HTTP with the standard library only (urllib), since the interpreters embedded in DCCs like Blender rarely have requests or httpx on hand. It also decodes the glTF 2.0 responses back into plain numpy arrays, so callers don't need a glTF library of their own. Install it with the base pip install motionmcp-sdk — no FastAPI/pydantic/uvicorn required.

from motionmcp import client

caps = client.get_capabilities(url)                      # GET /capabilities
model = client.pick_model(caps, wanted="kimodo-soma-rp")  # a model id from the capabilities
doc = client.generate(url, request_body, on_progress=print)  # POST /generate
samples = client.parse_gltf_samples(doc)                  # glTF JSON -> numpy arrays

See Client in the SDK docs for the full API.

What's NOT in v0

• Async jobs (POST /generate returning 202 Accepted, GET /generate/jobs/{id}). Sync only for now; planned for v0.2.
• Idempotency cache. Spec-recommended but not required.
• Binary glTF (model/gltf-binary). JSON only for now.
• fps resampling between request fps and the model's native fps. Backbones currently see request.fps(spec.fps) and are responsible for honoring it.
• Built-in retargeting. Set supports_retargeting=False and require the canonical skeleton, or implement retargeting in your generate().

These are deliberate v0 omissions to keep the surface tight. Feedback welcome on which to prioritise next.

Status

Alpha. The protocol is v1.0-rc1; the SDK API is v0.1. Expect minor shape changes before v1.0.

License

Apache 2.0.