Skip to main content

Python API for the MCWS interface of JRiver Media Center

Project description


A python API wrapper for MCWS, the web interface of the excellent JRiver Media Center. The aim is to replicate the MCWS functionality as close as possible in a pythonian, easy to use manner. Additionally, common use-cases can be implemented in easily accessible recipes.

Currently, the minimum required version of JRiver MC is 26. Backwards compatibility is possible, but will have to be requested - it is mainly the automatic field conversion that is preventing it.


use your package manager of choice to install pymcws:

pipenv install pymcws

First order of action is to import pymcws. You can just import the package and use it as a one-stop-shop-all:

import pymcws as mcws

using this method, all functions and recipes are imported and available via the mcws object. You can then initialize a server and start using commands:

office = mcws.get_media_server("AccessKey", "readonly", "supersecretpassword")
mcws.play_album(office, "Ludovico Einaudi", "I Giorni")
zones = mcws.playback_zones(office)
for zone in zones:
    print(zone.index,,, zone.guid, zone.is_dlna)
mcws.playback_playpause(office, zones[0])

For a full set of examples, please see


Contributions are very welcome. Please create pull requests at your leisure. If you are not of the coding kind, you can also leave a request for a specific functionality in the issue tracker.

Version History


  • Introduced session management for established media servers.


  • Added automatic field resolution. Fields are automatically converted to and from their corresponding python types by the API, sparing you the postprocessing.
  • Because of this, the required version of MC is now 26. Earlier version support is possible but needs to be requested.
  • Play recipes use more reasonable defaults for shuffle and repeat.
  • Several smaller bugfixes.


  • Added remote connection capabilities. The MediaServer class queries JRiver's web service and tries to determine the best possible connection method automatically.


  • Fixed zones being ignored in play_recipes.


  • Fixed failing package installation on case-aware file systems.


  • Created query recipes for easier querying.
  • Improved image and cover art handling.
  • Implemented library_values.
  • Implemented automatic query escaping for the jriver search language.
  • Play recipes allow setting shuffle and repeat states.
  • Introduced zone handling.
  • Full automatic local ip resolution, also for multiple network adapters.


  • Support for getting file info and parsing MPLs.
  • Support for getting images for library files.
  • More lenient timeouts for local connections should prevent huge queries from failing.


  • MediaServer now throws exception if key cannot be resolved instead of failing silently.
  • Added mute, shuffle and repeat.
  • Added volume control.
  • Improved to explain usage better.
  • Fixed wrong behavior of playback_stop.


  • now has a method to get a server directly from pymcws object. This allows basic usage by only importing pymcws.


  • Initial release and proof of concept.
  • Resolve media network access keys.
  • Issue playback commands.
  • Search and play files to different zones on server.
  • First play_recipes that facilitate playback of files.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pymcws, version 0.2.1
Filename, size File type Python version Upload date Hashes
Filename, size pymcws-0.2.1-py3-none-any.whl (13.2 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pymcws-0.2.1.tar.gz (12.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page