Process incoming JSON-RPC 2.0 requests in Python

Documentation | API reference | Examples | Changelog | Migration

jsonrpcserver takes a JSON-RPC 2.0 request, calls your Python function and gives you the response to send back. It leaves the networking to you, so it fits into whatever server you already have.

Features

• Works with any framework or transport. The docs have tested examples for http.server, Flask, Werkzeug, Django, FastAPI, aiohttp, Sanic, Tornado, websockets, ZeroMQ and Socket.IO.
• Sync and async: dispatch and async_dispatch. With async_dispatch, the requests in a batch run concurrently.
• Follows the spec for batches, notifications and errors, and checks each request's params against your function's signature.
• Keeps exception messages out of responses and in your logs, and limits batch size with max_batch_size (from 5.0.10).
• Typed: ships py.typed, and @method keeps your functions' signatures for mypy and pyright.
• Safe to call from several threads, and tested on Python 3.8 to 3.14, including free-threaded 3.14t.

Install

pip install jsonrpcserver

The latest release on PyPI is 5.0.9. This README and the documentation describe 5.0.10, which isn't released yet. 5.0.9 sends exception messages to clients. The Security page shows how to stop that, and the changelog lists the other differences.

Quickstart

Save this as server.py and run it with python server.py:

from jsonrpcserver import Result, Success, method, serve


@method
def ping() -> Result:
    return Success("pong")


if __name__ == "__main__":
    serve("localhost", 8000)

Then send it a request from another terminal:

curl -s -H 'Content-Type: application/json' -d '{"jsonrpc": "2.0", "method": "ping", "id": 1}' http://localhost:8000/

Output:

{"jsonrpc": "2.0", "result": "pong", "id": 1}

serve() is a small server for trying things out. In your own framework, pass the request body to dispatch and send back the string it returns. The examples show how.

Security

Before you put a server on the internet, pass max_batch_size to dispatch and limit the request body size in your framework. Upgrade to 5.0.10 when it's out. The Security page explains why.

Documentation

• Documentation: guides, framework examples and the API reference.
• Migrating from 4.x: methods must now return Success(value). A 4.x method that returns a plain value still runs, but the client gets an Internal error.
• Contributing and the security policy.
• License: MIT.

See also

jsonrpcclient (GitHub) creates JSON-RPC requests and parses the responses in Python. It's the client-side companion to this library, and its quickstart talks to the server above.

Credits

Created by Beau Barker. Maintained by Synapse Research.