Pad MCP server
Commit Nov 15, 2026Provides a local-first project management system with a CLI, web UI, and native AI agent skills for managing tasks, plans, and playbooks.
Also known as PerpetualSoftware/pad
- Stars
- 207
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is Pad MCP?
Pad provides a local-first project management system with a CLI, web UI, and native AI agent skills for managing tasks, plans, and playbooks.
Summary generated from the project's README
About Pad MCP server
Managing development workflows and project tasks directly from your terminal or local environment is what Pad enables for developers. This local-first project management system uses a SQLite backend to ensure your data stays on your machine, providing a CLI, a web UI at localhost:7777, and native skills for AI agents. It is designed to work alongside coding tools like Claude Code, Cursor, and Windsurf, allowing them to act as project partners by reading and updating tasks, plans, and playbooks.
Users can organize work into collections such as tasks, ideas, and documentation, or create custom collections with specific typed fields. The system supports automated onboarding through the /pad onboard command, which helps agents adapt to a codebase by inspecting tools and setting up conventions. While it functions entirely offline, users can opt into Pad Cloud for synchronization and team collaboration. Setup is handled via a single command, pad init, which configures the workspace and AI skills automatically.
What you can do with it
- 1Onboard an AI agentAn agent can automatically learn your project's build tools and conventions by running a specific onboarding command.
- 2Manage tasks via terminalDevelopers can create and search for work items without leaving their command line interface.
- 3Track project progress visuallyUse a web-based dashboard to view active work, plan progress, and upcoming priorities.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
PAD_AGENTPAD_TOKEN
| Name | Description | |
|---|---|---|
| PAD_AGENT | — | |
| PAD_TOKEN | — |
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubOne binary. Local-first. No sign-up. Pad gives you a CLI, a web UI, and an AI agent skill — all backed by SQLite, all running on your machine. Your project data stays on your laptop — unless you take it to Pad Cloud.
Quick Start
brew install PerpetualSoftware/tap/pad
cd your-project
pad init # configure, auth, workspace, AI skill — all in one
pad server open # opens the web UI at localhost:7777
pad init is the smart entry point — it auto-detects what's needed, walks you through each step, and is safe to re-run anytime (it skips finished steps and prints a status summary).
Then, in a fresh agent session in your project, say:
/pad onboard
Your new workspace ships with the canonical onboard playbook auto-activated. The agent walks an interview, inspects your codebase if it has shell access, and adapts your workspace's collections, conventions, roles, and playbooks to match the project. It's the fastest way to go from empty workspace to "okay, this is mine."
Why Pad?
Tools like Linear, Jira, and Notion are built for teams on the cloud. Pad is built for developers on their machine — and for the AI agents working alongside them. When you do want your projects on every device or a teammate on the board, Pad Cloud hosts the same product with sync, workspace invites, and role-based access. A self-hosted workspace moves there by export and import; see the move-to-Cloud guide.
| Pad | Linear / Jira | Notion | |
|---|---|---|---|
| Setup | pad init |
Create account, invite team, configure | Create account, pick template |
| AI agents | Native /pad skill for 7+ tools |
Third-party integrations | Third-party integrations |
| Data | Local SQLite you own — or opt-in Pad Cloud | Their cloud | Their cloud |
| Offline | Full functionality | Read-only cache at best | Limited |
| CLI | First-class | Afterthought | None |
| Price | Free, open source | Per-seat pricing | Per-seat pricing |
Features
For Developers
CLI that doesn't get in your way. Create tasks, search items, check status — without leaving the terminal.
pad item create task "Fix OAuth redirect" --priority high
pad item create idea "Real-time collaboration" --category infrastructure
pad item list tasks --status in-progress
pad item search "authentication"
pad project dashboard # Project dashboard
pad project next # What should I work on?
pad server info # How this client is connected to Pad
Web UI that stays out of your way. A clean interface at localhost:7777, in dark and light themes, with:
- Board, list, and table views — drag-and-drop between status columns
- Keyboard navigation —
j/kto move,Enterto open,Escto go back,Cmd+Kto search - Rich text editor — Tiptap-based with markdown and auto-save, and real-time co-editing
- Wiki-links — type
[[Title]]to link between items - Real-time updates — an agent creates a task in the terminal, it appears in the browser instantly
- History — every change is versioned, with who made it: a person, or a named agent
- Dashboard — active work, plan progress, what needs attention, and what to do next
For AI Agents
Using Claude Code? Install the Pad plugin. It bundles the /pad skill, typed shortcuts (/pad:status, /pad:capture, /pad:onboard), live item notifications and a side panel (/pad-pane), and it updates itself:
/plugin marketplace add PerpetualSoftware/pad
/plugin install pad@pad
In the Claude Desktop app's Code tab: + → Plugins, add the marketplace PerpetualSoftware/pad, then install pad. Open the panel with /pad-pane. If nothing is set up yet, it walks you through connecting to Pad Cloud, installing Pad on this machine, or linking your own server. The panel needs Claude Code 2.1.287 or later; the skills work on any version.
Your agent becomes a project partner. Install the /pad skill once, and your AI coding tool can read, create, and update project items through natural language. Cursor, Codex, Windsurf, and OpenCode receive a compact dispatcher, reuse bootstrapped context within a conversation, and load detailed guidance by topic with pad agent guide, keeping routine turns small.
pad agent install # Auto-detects your tools and installs the skill
Works with Claude Code, Cursor, Windsurf, Codex, OpenCode, GitHub Copilot, Amazon Q, and JetBrains Junie.
Then just talk to your project:
> /pad what should I work on next?
> /pad I finished the OAuth fix
> /pad create a task to add rate limiting
> /pad let's brainstorm about the API redesign
Conventions and playbooks teach agents how your project works:
- Conventions — trigger-based rules like "run tests before marking a task done" or "use conventional commits"
- Playbooks — multi-step workflows like "when implementing a feature: read the spec, create a branch, write tests first, then implement". Playbooks can declare a kebab-case
invocation_slugso users can invoke them directly:/pad ship PLAN-42,/pad release 0.5.0. Freshstartupworkspaces ship a genericshipplaybook out of the box.
pad item create convention "Run tests before completing tasks" \
--field trigger=on-task-complete \
--field scope=all \
--field priority=must
Agents load relevant conventions automatically, and every agent action is attributed in the activity feed — so you can see what the AI changed rather than finding it later in a diff.
Name your agents. An agent that identifies itself gets its name on its writes: in the activity feed, the dashboard, item timelines and the admin audit log. Pad takes the first of these it finds:
pad session register --agent rook # 0. this session's registered name
# 1. agent_name = "reviewer" in .pad.toml (per workspace, committed)
export PAD_AGENT=reviewer # 2. per process
# 3. otherwise the detected runtime, e.g. "claude-code"
With none of these, the write is recorded as the person whose credentials it used. The name is self-declared, so it labels a trail rather than proving who acted; provenance surfaces show both, e.g. reviewer (via Dana). pad session list shows which registered sessions on this machine are alive, and as which agent.
Onboard agents to a new codebase:
Open an agent session in the workspace directory and run /pad onboard. The agent walks an interview, detects your build/test/CI tooling, and adapts your workspace's collections, conventions, roles, and playbooks to match the project. Works for any agent that speaks Pad — Claude Code, MCP-only agents, etc.
Collections & Custom Fields
Pad organizes work into collections — typed containers with structured fields.
Built-in collections:
| Collection | Purpose |
|---|---|
| Tasks | Work items with status, priority, assignee, effort, due date |
| Ideas | Feature ideas with impact and category |
| Plans | Project milestones with progress tracking |
| Docs | Documentation, decisions, reference material |
| Conventions | Project rules that guide agent behavior |
| Playbooks | Multi-step workflows for agents to follow |
Create your own with typed fields — select, text, date, number, url, relation, checkbox:
pad collection create "Bug Reports" \
--fields "severity:select:low,medium,high,critical; browser:text; reproducible:checkbox"
Items get reference numbers automatically (TASK-5, BUG-12) and can be moved between collections with field migration.
Installation
Homebrew (macOS and Linux)
brew install PerpetualSoftware/tap/pad
Build from Source
git clone https://github.com/PerpetualSoftware/pad
cd pad
make build
cp pad ~/.local/bin/ # or /usr/local/bin/
Requires Go 1.26+ and Node.js 22+. Alternatively, nix develop provides a shell with the exact Go and Node versions pinned — see the Nix section below.
The go install github.com/PerpetualSoftware/pad/cmd/pad@latest path is not supported for the full Pad binary, because the web UI must be built and embedded during the source build.
Docker
docker run -p 127.0.0.1:7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad
This publishes Pad to localhost:7777 on the host machine, which is the recommended default for local use.
Pin a version for anything you keep. The untagged name is latest, which moves to each new stable release (never a release candidate) the next time the image is pulled. Name the release instead, as a bare version with no leading v, for example ghcr.io/perpetualsoftware/pad:0.17.2, and change the tag when you choose to upgrade. Every published image is multi-arch and cosign-signed.
First run — create the first admin. Open http://localhost:7777 and you'll hit a setup page asking for a bootstrap token. On first start with no users, Pad logs a one-time setup URL to stderr (captured by docker logs) — grep it and open the printed link:
docker logs <container> 2>&1 | grep -A6 'Pad first-run setup'
# → http://<your-host>:7777/setup#token=<one-time-token>
Open that URL, create your admin account, and the token is consumed (the banner stops appearing). If you'd rather stay on the CLI, docker exec -it <container> pad auth setup works too — running inside the container counts as loopback, which the bootstrap gate allows. On a network you already trust, set PAD_BYPASS_SETUP_TOKEN=true to skip the token and create the admin straight from http://<your-host>:7777/setup (only safe when the port isn't reachable from the open internet).
Single user, more than one device? Publish to all interfaces so you can reach Pad from your phone, tablet, or another machine on the same LAN, Tailscale network, or home VPN:
docker run -p 7777:7777 -v pad-data:/data ghcr.io/perpetualsoftware/pad
Set PUID / PGID to match your host's file ownership: the entrypoint runs Pad as that user. The defaults, 99/100, are Unraid's nobody:users.
For multi-instance deployments, Pad supports Postgres + Redis via docker-compose.yml — see docs/deployment.md for the full setup. The compose file runs the released image; set PAD_VERSION in .env to pin it.
Nix
Run without installing:
nix run github:PerpetualSoftware/pad
Or install into your profile:
nix profile install github:PerpetualSoftware/pad
A flake devShell (Go, Node, and friends, pinned to the same versions CI uses) is also available for contributors:
nix develop
A
nixpkgspackage (nix-shell -p pad/environment.systemPackages) is planned but not yet merged upstream. Until then, use thegithub:PerpetualSoftware/padflake reference above.
Binary Download
Pre-built binaries for macOS, Linux, and Windows are available on the releases page.
Pad Cloud (hosted)
Don't want to run anything? Pad Cloud is the managed option — same product, same CLI, same /pad skill, free during beta. Sign up on the web, then connect a project directory:
pad init --url https://app.getpad.dev --workspace my-workspace
Self-hosting stays first-class: the binary is unchanged and no features are Cloud-only.
Upgrading Pad
Pad ships a new binary on a roughly weekly cadence. Upgrades are designed to be boring: install the new binary and restart. Database migrations run automatically at startup, only the ones your database is missing are applied, and each migration commits atomically (a failed migration rolls back cleanly and is retried next boot).
The one rule: only ever move forward. Newer binaries know how to migrate an older database; older binaries do not understand a newer schema. Since Pad added its schema-ahead guard, a downgraded binary that finds a database newer than itself refuses to start rather than silently running old code against a newer schema (which can corrupt data):
database schema is newer than this pad binary: ... This almost always means the
binary was DOWNGRADED (e.g. brew/docker rollback) ... Upgrade pad back to a build
that includes those migrations, or re-run with `pad start --force`.
To recover, reinstall the newer binary (brew upgrade pad, pull the newer Docker tag, etc.). If you have intentionally downgraded and accept the risk, start with pad start --force (or set PAD_ALLOW_SCHEMA_AHEAD=1) to override the guard.
Automatic pre-migration snapshot (SQLite). Whenever a SQLite-backed instance has pending migrations to apply, Pad first copies the database file to pad.db.pre-<version> next to it. If an upgrade ever goes wrong, stop the server and copy that snapshot back over pad.db. This is a convenience net, not a backup strategy — keep your own backups (see docs/backup.md). PostgreSQL instances are skipped here; use pg_dump or a provider snapshot before upgrading.
Recommended upgrade flow:
# 1. Back up first (SQLite shown; see docs/backup.md for Postgres)
pad db backup -o pad-backup-$(date +%Y%m%d).db
# 2. Stop the server, install the new binary, restart
# (migrations + the pre-migration snapshot run automatically on start)
brew upgrade pad # or: a new image tag (see Docker above), binary download, make install
# 3. Confirm it's healthy
pad --version
curl -s localhost:7777/api/v1/health
Getting Started
1. Set up Pad
cd ~/projects/myapp
pad init "My App"
pad init is the smart entry point that handles everything in one command:
- Configures this client's connection (local server, remote, or Docker)
- Auto-starts the local server
- Creates the first admin account on a fresh local install (Docker / remote hosts run
pad auth setupon the server instead) - Logs you in if needed
- Creates or links a workspace for the current directory (writes
.pad.toml) - Installs the
/padskill for any AI tools detected in the project
Run from your project root. Safe to re-run anytime — it skips finished steps and prints a status summary if nothing's needed.
Choose a template with --template, or omit it for an interactive picker grouped by category (Software / People / …):
pad workspace init --list-templates # See the full catalog grouped by category
pad init "My App" --template scrum # Scrum-style with sprints
pad init "My App" --template product # Product management focused
pad init "My Hiring" --template hiring # Company-side: requisitions, candidates, interview loops, feedback
pad init "Job Search" --template interviewing # Candidate-side: applications, interviews, companies, contacts
pad init "My App" --template blank # Custom: system collections only — let /pad onboard build the rest
Pad ships templates for software (startup / scrum / product), people workflows (hiring, interviewing), and a custom blank template — system collections (Conventions, Playbooks) only, with the /pad onboard playbook as its sole seeded content. blank is the entry point for the agent-driven /pad onboard flow: it walks you through shaping collections, conventions, and roles to match your actual project. Reserved categories for research, content, operations, and personal use await their first templates, so the same project-management primitives fit well beyond code projects. There's also a hidden demo template — the startup layout pre-loaded with realistic sample data — that's kept out of the picker but can be built explicitly with --template demo.
2. Start working
# From the CLI
pad item create task "Set up CI pipeline" --priority high
pad item create idea "Add WebSocket support" --category infrastructure
pad project dashboard
# From the web UI
pad server open # Opens localhost:7777 in your browser
# From your AI agent
# Just use /pad in Claude Code, Cursor, etc.
3. Teach your agents the rules
In an agent session inside the workspace:
/pad onboard
The agent walks an interview, detects your tooling, and adapts the workspace's collections, conventions, roles, and playbooks. To browse the library directly:
pad library list --type conventions # Pre-built conventions you can adopt
pad library list --type playbooks # Pre-built multi-step workflows
4. Optional — connect a desktop AI app via MCP
Pad ships an MCP (Model Context Protocol) server so Claude Desktop, Cursor, Windsurf, Claude Code, or Codex can manage items, plans, ideas, and dependencies as native tools, read workspace state by URL, and load multi-step workflows as prompts.
pad mcp install claude-desktop # or: cursor, windsurf, claude-code, codex, --all
Pad MCP questions
How do I get started with Pad?
You can use the pad init command to configure your workspace, authentication, and AI skills in one step.
Where is my project data stored?
Your data is stored locally in a SQLite database on your machine, though you can opt-in to use Pad Cloud for syncing.
Can I use Pad offline?
Yes, Pad offers full functionality while offline because it is a local-first tool.