serverpod Serverpod Overview
Serverpod is an open-source backend framework for Flutter written in Dart. A Serverpod project consists of usually three packages:
my_project_server - the server code.
my_project_client - generated client code.
my_project_flutter - a Flutter app (imports the client).
There can also be packages that share code, e.g., my_project_shared.
The server starts in lib/server.dart, which creates the generated Serverpod class from src/generated/serverpod.dart (pre-wired with the project's protocol and endpoints) with final pod = Serverpod(args); and then await pod.start();.
The server exposes endpoint classes that the client calls via generated RPC client. Add methods to the endpoints, the code generation will recreate them on the client side. Models are defined in YAML and generate Dart classes for both server and client.
Serverpod projects use a PostgreSQL database for persistence (SQLite is also supported) and include an ORM, caching, real-time streaming (using Dart streams), file uploads, scheduling (called future calls), logging, and a built-in web server (Relic).
Each of these feature areas has its own serverpod-* skill; use the one that matches the task. The Insights companion app is not covered by a skill and is documented at https://docs.serverpod.dev.
Running the server
The user runs the server with serverpod start, which watches for file changes to run incremental code generation and hot reload the server (and the Flutter app, when the project has one).
Do not check whether the server is running before acting: make the changes and call the serverpod MCP tools. When nothing is running, the MCP answers with an explicit "the server is not running" error. Only then, stop and ask the user to start it. NEVER start the server yourself.
ALWAYS use the MCP server instead of the command line. A running serverpod start exposes:
create_migrationandapply_migrationsfor the database (after you change data models).create_repair_migrationwhen the database has drifted out of sync with the migrations. It only writes the repair file; follow up withapply_migrations.tail_server_logsto read logs from the server.tail_flutter_logsto read raw stdout/stderr from a Flutter app.hot_reloadto reload the server and the Flutter app while keeping in-memory state. Only needed with--no-watch, sinceserverpod startreloads on file changes.hot_restartto restart the server and the Flutter app, dropping in-memory state. ALWAYS call it after doing changes in the Flutter app that may not work with normal hot reload (which is automatically applied).spawn_flutter_appto start a Flutter app declared underserverpod: flutter_apps:in the serverpubspec.yaml.get_flutter_app_dtdto get the Dart Tooling Daemon URI of a running Flutter app. Pass it to thedartMCP to drive the app.
Tools that target a Flutter app take an optional appId, which is the map key under serverpod: flutter_apps:. It is required only when the project declares more than one app.
Working on the project with no running instance
- NEVER use the CLI unless you have already attempted to use the MCP.
- ONLY if you cannot connect to the MCP server, the code can be generated by calling
serverpod generate. - NEVER edit the generated code, as it will be overwritten by the next generation. This does not cover the SQL of a created migration, which may be edited — see the Serverpod Migrations skill.
After generating the code, database migrations can be created by calling serverpod create-migration. Use ONLY if you cannot use the MCP.
# Use `--force` to create migrations with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-migration [--force] [--tag <tag>]
See the Serverpod Migrations skill for more details.
Checklist after doing changes:
dart analyze(CLI, or thedartMCP server)dart format(CLI, or thedartMCP server)- Do
serverpodMCPhot_restartif required (hot reload is done automatically). Will also hot restart Flutter app - Check
serverpodMCPtail_server_logs(andtail_flutter_logsfor a Flutter app) for any issues