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 batches to 100 requests by default (max_batch_size).
• 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.11 to 3.14, including free-threaded 3.14t.
• No dependencies, from 6.0.

Install

pip install jsonrpcserver

If you're on 5.0.9 or older, upgrade: those versions send exception messages to clients. 6.0 is a release candidate: pip install --pre jsonrpcserver installs it. The migration guide lists what changes from 5.x.

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. Run 5.0.10 or later. The Security page explains why.

Documentation

• Documentation: guides, framework examples and the API reference. The menu next to the title switches between the docs for 5.x and 6.0.
• Migrating from 4.x: methods return Success(value) or Error(...). From 5.1.0 a method can also return a plain value, as in 4.x.
• Contributing and the security policy, which says which versions get fixes.
• 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.