MCP server that provides planning tooling.
mcp-plan is packaged as a Nix flake. Run it directly without installing:
nix run github:haras-unicorn/mcp-plan -- runor build the mcp-plan binary with:
nix build github:haras-unicorn/mcp-planPrebuilt binaries for x86_64-linux and aarch64-linux, for each supported
database backend (sqlite, postgres, mysql or all), are attached to each
GitHub release as tarballs containing the mcp-plan binary.
To run with a specific backend (in this example sqlite) from releases:
curl -L -o mcp-plan.tar.gz \
https://github.com/haras-unicorn/mcp-plan/releases/latest/download/mcp-plan-x86_64-linux-sqlite.tar.gz
tar -xzf mcp-plan.tar.gz
./mcp-plan-x86_64-linux-sqlite runTo run with a binary supporting all backends from releases:
curl -L -o mcp-plan.tar.gz \
https://github.com/haras-unicorn/mcp-plan/releases/latest/download/mcp-plan-x86_64-linux.tar.gz
tar -xzf mcp-plan.tar.gz
./mcp-plan-x86_64-linux runPick the archive matching your backend:
mcp-plan-x86_64-linux.tar.gz(all backends)mcp-plan-x86_64-linux-sqlite.tar.gzmcp-plan-x86_64-linux-postgres.tar.gzmcp-plan-x86_64-linux-mysql.tar.gzmcp-plan-aarch64-linux.tar.gz(all backends)mcp-plan-aarch64-linux-{sqlite,postgres,mysql}.tar.gz
Add the flake as an input and apply its overlay so that mcp-plan is available
in your system configuration:
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
mcp-plan.url = "github:haras-unicorn/mcp-plan";
};
outputs =
{ nixpkgs, mcp-plan, ... }:
{
nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
modules = [
{ nixpkgs.overlays = [ mcp-plan.overlays.default ]; }
];
};
};
}Then add pkgs.mcp-plan to your packages, either in NixOS:
{ pkgs, ... }:
{
environment.systemPackages = [ pkgs.mcp-plan ];
}or with home-manager:
{ pkgs, ... }:
{
home.packages = [ pkgs.mcp-plan ];
}Builds are cached on the haras cachix cache. When the flake is used directly
(for example with nix run github:haras-unicorn/mcp-plan), the cache is
configured automatically through the flake's nixConfig. To use it when the
package comes from an overlay, add the following to your nix configuration:
{
nix.settings = {
substituters = [ "https://haras.cachix.org" ];
trusted-public-keys = [
"haras.cachix.org-1:/HIo1JYqOIH1Nwk1EGXhuPPvDW0WekxIbY5CiXUZbYw="
];
};
}mcp-plan is an MCP server that speaks the Model Context Protocol over stdio.
Add it as a stdio MCP server to any MCP client, for example:
{
"mcpServers": {
"mcp-plan": {
"command": "nix",
"args": ["run", "github:haras-unicorn/mcp-plan", "--", "run"]
}
}
}If mcp-plan is already on your PATH, point the client at the binary directly
instead:
{
"mcpServers": {
"mcp-plan": {
"command": "mcp-plan",
"args": ["run"]
}
}
}mcp-plan reads its configuration from config.toml in the working directory,
overlaid with MCP_PLAN_* environment variables. Every setting is optional. The
full schema and a worked example live in the References section.
The binary accepts a subcommand:
mcp-plan run— start the MCP server over stdio (default).mcp-plan migrate— open the database and apply pending migrations, then exit.mcp-plan schema— write the configuration JSON schema to--output.
--config <path> is a global flag selecting a different configuration file
(defaults to config.toml), for example:
mcp-plan --config ./prod.toml migrate run[database]
url = "sqlite://data/mcp-plan.db"The file is split into three sections:
database— the databaseurl. See below for the supported schemes.runtime—tps_in,tps_out,max_task_duration_secs,queue_limit,max_retries.sources— a list of statically configured sources.
See the JSON schema and the example for the exact keys and defaults (References below).
Environment variables override file values. Use the MCP_PLAN prefix with __
as the section separator:
MCP_PLAN__RUNTIME__TPS_IN=1000 mcp-plan runLogs are emitted as newline-delimited JSON on stderr, keeping stdout
exclusively for the MCP JSON-RPC protocol. Each line carries a level,
timestamp, target, a human-readable message, and structured fields (e.g.
task_id, duration_ms) that are safe to query with jq:
RUST_LOG=debug mcp-plan run 2> >(jq -r '"\(.level): \(.message)"')Log verbosity is controlled via RUST_LOG (default info). Any standard
tracing filter is accepted (error, warn, info, debug, trace,
per-target filters, etc.).
database.url selects the backend by scheme:
sqlite://data/mcp-plan.db— a SQLite file (relative to the working directory). The database file and its parent directory are created on first start. Use an absolute path (e.g.sqlite:///var/lib/mcp-plan.db) orsqlite://:memory:for an in-memory database.postgres://user:password@host:port/database— PostgreSQL.mysql://user:password@host:port/database— MySQL.
Each binary is built against a single backend (sqlite by default, or the
postgres/mysql build variants from the releases).
Both run and migrate connect to the database and apply pending migrations at
startup; migrate exits immediately afterwards so migrations can be run as a
separate init step (e.g. in multi-tenant deployments). SQLite runs in WAL mode
with foreign keys enabled.
mcp-plan is a regular MCP server, so any MCP client — including a custom agent
runtime — can drive it. Register it as a stdio server (see the Usage
example) and expose the plan__* tools to your agent.
To keep an autonomous agent working over time, add a scheduler of your choice (a
cron entry, a CI scheduled job, a loop inside an existing daemon or an OpenClaw
heartbeat/agent cron job) that periodically connects to mcp-plan and instructs
the agent to run a planning/delegation pass. An example heartbeat prompt is
provided in References section—you can point a cron job at it
verbatim or use it as a template:
# example: run an agent-driven planning pass on an interval
*/30 * * * * mcp-plan-with-agent --instruct assets/heartbeat.mdExact wiring depends on your runtime; the example shows the shape. The tasks and sources live in the database, so each pass should continue where the previous one stopped.
The JSON schema, an example configuration, and an example heartbeat are
generated and versioned under assets:
The documentation is available at https://haras-unicorn.github.io/mcp-plan/.