Gimme MCP
OfficialThe server manages Ubuntu host provisioning and Deployer-based PHP application deployment through reviewable plans.
Inspect a configured Ubuntu host's OS, runtime commands, service states, and non-interactive sudo availability.
Plan and provision the host APT stack, installing missing packages and enabling PostgreSQL/Valkey; stale or invented plan IDs are rejected.
Register and list PHP applications with pinned Git repositories, branches, framework recipes, and optional frontend build settings.
Plan and provision application resources: PostgreSQL database and role, Valkey namespace, and protected remote environment file.
Plan and deploy registered applications from Git using a pinned Deployer recipe, including recipe-defined migrations.
List retained releases and identify the current release for an application.
Roll back an application to its previous good release after explicit confirmation.
Report systemd service status for only postgresql, valkey-server, and caddy.
Generates Caddy site configurations for registered applications, validates the full Caddy configuration, reloads Caddy, and uses Caddy's local CA for HTTPS certificates.
Supports deployment of Next.js static exports via the out directory.
Builds static frontends and PHP frontend assets by running npm ci from the committed lockfile followed by a validated npm script.
Supports deployment of Nuxt-generated static sites via the .output/public directory.
Deploys registered PHP applications, configuring PHP-FPM and application public directories for serving.
Creates isolated per-app PostgreSQL roles and databases via local peer authentication, with passwords generated on the remote host.
Provisions and manages a fixed Ubuntu host, installing system packages and managing systemd services according to a declared stack manifest.
Supports deployment of Vite/static frontend applications, with configurable output directories and npm-based builds.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gimme MCP plan the stack before provisioning devbox"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gimme MCP
Gimme is an alpha MCP deployment control plane for Ubuntu targets. It keeps desired state locally, provisions a target through a narrowly scoped privileged helper, and deploys PHP/Laravel or static applications through Deployer.
Contents
Version 0.6 has four explicit resources:
a target is an independently provisioned Ubuntu machine;
an application is reusable source/build metadata;
a resource is a named, version-pinned PostgreSQL or Valkey service;
a deployment places one application revision on one target at one stage.
This is alpha software and 0.6 is a hard state/API break. There are no compatibility tools. The migration preserves existing remote paths, database identities, cache prefixes, and URLs while recording observed runtime and service versions explicitly.
Related MCP server: dokku-mcp
Capability roadmap
Gimme keeps provider, Resource, Target capability, and execution-engine concerns separate. The table records the public scope rather than promising that a provider's entire platform API is available. Available capabilities have a supported schema and plan/apply workflow; Proposed capabilities are described by an ADR but have no implementation contract yet; Planned and Deferred entries are direction, not commitments.
Layer | Module or capability | Status | Scope |
Execution | Ubuntu Target / | Available | Fixed, policy-bound deployment processes on registered Ubuntu Targets. |
Execution | Explicit Execution Profiles | Proposed | Portable Deployment intent rendered by a bounded engine adapter; see ADR 0010. |
Execution | Docker Compose | Planned | First container renderer while retaining a registered Target boundary. |
Execution | AWS ECS/Fargate | Planned | First managed/cloud execution renderer. |
Execution | EKS/Kubernetes and Lambda | Deferred | Require separate, narrow workload contracts; arbitrary manifests and provider configuration remain out of scope. |
Target capability | Explicit Target Capability Profiles | Proposed | Fixed host catalog such as |
Relational Resource | PostgreSQL | Available |
|
Relational Resource | MySQL | Planned | Exact engine contract; provider adapters remain separate work. |
Relational Resource | MariaDB | Planned | Exact engine contract, distinct from MySQL despite protocol compatibility. |
Data-store Resource | Valkey | Available |
|
Data-store Resource | Memcached | Planned | Ephemeral cache contract, distinct from Valkey. |
Data-store Resource | DynamoDB-backed cache | Planned | AWS Resource contract with bounded table, TTL, region, and workload-identity policy. |
Search Resource | Meilisearch | Planned | A bounded search Resource contract rather than a generic package installation. |
Object storage | Artifact and Recovery stores | Available | Versioned S3-compatible stores for immutable artifacts and Recovery Points. |
Object storage | Application object-storage binding | Planned | A separately scoped Resource contract for application-managed assets. |
Queues | Database and Valkey-backed Laravel workers | Available | Existing bounded worker and scheduler process behavior. |
Queues | SQS-compatible queue binding | Planned | External queue Resource/binding contract. |
Provider foundation | Ubuntu Targets | Available | Operator-registered machine identities, network policy, exact APT stack, and mise policy. |
Provider foundation | AWS | Available, bounded | Secrets Manager, S3-compatible stores, RDS PostgreSQL, ElastiCache Valkey, and the supported AWS HA topology only. |
The proposed execution and Target-capability model is intentionally not a generic infrastructure provisioner. It does not accept arbitrary shell, package lists, Compose files, ECS task definitions, Kubernetes YAML, Helm values, IAM policies, or ingress snippets. See ADR 0010 for the intended portable intent, renderer, and migration boundaries.
Safety model
Gimme deliberately exposes no arbitrary shell, SQL, hostname, package, service, or filesystem-path parameters. Remote mutations use reviewable, content-addressed plans. Applying a stale plan fails closed. Deployment placement is allocated once and cannot be changed through the update API.
Repository URLs must be credential-free. Authentication belongs in SSH agents, repository-scoped deploy keys, or credential helpers. The Deployer child receives an explicit environment allowlist, so unrelated shell credentials are not inherited.
Secrets are bounded {store, secret, field} references, never plaintext MCP arguments or
tool output. The built-in local-sops store resolves from secrets.enc.json; registered
AWS Secrets Manager stores use separate inspection and resolver roles. Values are placed in
an owner-only temporary file, transferred to an owner-only remote temporary file, and
removed after environment reconciliation. See
docs/how-to/use-aws-secret-stores.md.
Create or edit the encrypted document with sops config/secrets.enc.json; its nested
JSON keys must match the references declared by deployments. Configure age through
SOPS_AGE_KEY_FILE or SOPS_AGE_KEY in the MCP server's environment.
Production is policy, not a branch convention. A production deployment requires:
a
public_dnstarget and explicit domain;an exact commit source;
APP_ENV=productionandAPP_DEBUG=false;named health probes at explicitly selected candidate and live phases.
Staging also requires debug off plus candidate and live health gates. Local and preview deployments are less restrictive. Caddy uses its internal CA for local mDNS and automatic ACME HTTPS for public DNS.
Install
# From the repository root:
uv sync
composer installState defaults to config/state.json. Set GIMME_STATE_DIR to keep operational state
elsewhere; the directory contains:
state.json # schema-v8 desired state, fleet capacity, stores, pins, and Rollouts
secrets.enc.json # SOPS-encrypted secret values
.gimme.lock # local atomic-write lock
operations.jsonl # append-only, secret-safe plan/apply/outcome evidence
.gimme-journal.lock # local journal append lock
applied-secrets/ # secret-free Applied Secret Manifest fingerprints
deployment-locks/ # owner-only Deployment resource locksOperational state and encrypted secrets are ignored in this public source repository
because even encrypted documents, hostnames, repository URLs, and secret key names can
reveal private inventory. To make state Git-backed, point GIMME_STATE_DIR at a
separate private repository. Legacy 0.4 manifests remain ignored for the same reason.
Copy the example for a new installation, or use the migration tools for an older installation:
call
plan_state_migration; schema-v5 and older inputs also require an explicit release mode for every Deployment and any Artifact Store/Application build policy required by artifact mode;review its preserved placements and effects;
pass the exact
plan_idand any required older-schema policy toapply_state_migration;commit the resulting desired state only if that repository is intended to hold your operational inventory.
All reviewed plans include an execution_fingerprint covering Gimme, Deployer, privileged
helper, and dependency-lock inputs. Changing executable control-plane code after planning
invalidates the plan before apply; documentation and test-only changes do not.
See config/state.example.json for the complete shape.
For a public target, use network.mode: "public_dns", omit mdns_name, declare one
or more literal expected_addresses, and give every deployment an explicit domain.
Planning verifies that DNS resolves to a declared address before Caddy is allowed to
request an ACME certificate.
For guided workflows, see:
Target bootstrap
SSH must work against bootstrap_hostname. For local targets, normal operations use
the advertised hostname, which lets host-specific SSH settings such as agent
forwarding apply consistently.
The MCP server never handles a sudo password. Perform the initial helper installation from a terminal:
uv run gimme-bootstrap-target devbox
uv run gimme-bootstrap-database devboxThis keeps one interactive terminal open for sudo and installs root-owned, policy-bound helpers. Later MCP reconciliations use only those exact sudo rules. Run the bootstrap command again after changing the target's stack policy or upgrading Gimme's helper implementation. The bootstrap command inherits the terminal directly, so the password prompt appears live and input remains hidden; do not run it through a non-interactive pipe.
The second command grants the deployment user PostgreSQL CREATEDB and CREATEROLE;
they allow database lifecycle management but do not grant operating-system root.
For a local mDNS target, import the exported Caddy public root once on each development workstation. The CA private key never leaves the target:
scp devbox.local:/srv/gimme/apps/.caddy-local-root.crt /tmp/gimme-caddy-root.crtTrust only a CA retrieved from a target you control.
Runtime versions
Every deployment declares exact runtime versions. A pin has a provider and a
version; Gimme never resolves ranges such as latest, ^22, or 8.4.*.
systemselects an exact host binary and verifies its full version.miseinstalls and executes that exact user-space runtime from<apps_root>/.gimme/misewithout shell activation.bundledis valid only for npm, whose version is supplied by the selected Node.js.
Set target.runtimes.mise_version whenever any deployment uses mise and include
mise plus software-properties-common in the target stack. On Ubuntu 26.04 Gimme's
privileged helper enables only the fixed official ppa:jdxcode/mise source; it never
pipes a remote installer into a privileged shell. Use
plan_deployment_runtimes and apply_deployment_runtimes to review and install the
declared mise pins. Multiple Node.js, Bun, pnpm, Yarn, Python, Ruby, Go, and Java
versions can coexist because each deployment command runs through
mise exec tool@version.
PHP web deployments deliberately use the system provider: the exact PHP patch is
verified, Deployer uses /usr/bin/phpX.Y, Caddy uses
/run/php/phpX.Y-fpm.sock, and queue/Horizon/scheduler units use that same CLI.
Composer is also system-pinned so it cannot silently execute under another PHP.
Application php_extensions are exact required capabilities checked before deploy;
their packages remain part of the target's reviewed APT stack.
PostgreSQL and Valkey are named resources with explicit versions and deployment
bindings. The current target_local provider permits one version of each service per
target; the model leaves room for external or isolated providers later without
changing deployment identity.
Frontend builds
Applications may select npm, pnpm, yarn, or bun. The deployment declares exact
runtime versions and verifies them before running a build. Gimme accepts
only a validated script name, never a free-form command, and requires exactly one
matching lockfile with no conflicting package-manager lockfiles.
Manager | Frozen install |
npm |
|
pnpm |
|
Yarn 1 |
|
Yarn 2+ |
|
Bun |
|
Gimme will not silently substitute a package manager or update a lockfile.
Run
uv run gimme-mcpExample stdio client configuration:
{
"mcpServers": {
"gimme": {
"command": "uv",
"args": ["--directory", "/path/to/gimme", "run", "gimme-mcp"]
}
}
}Workflow
Register or migrate targets, applications, and resources; use
plan_register_deployment/register_deploymentfor reviewed explicit or fleet placement.inspect_target, thenplan_target_stack/apply_target_stack.plan_deployment_runtimes/apply_deployment_runtimesto install and verify pins.plan_deployment_resources/apply_deployment_resourcesto reconcile routing, PostgreSQL, Valkey, runtime values, workers, Horizon, and the scheduler.For artifact mode,
plan_build_artifact/build_artifacton the Build Target. Then useplan_deploymentto review the exact publication (or inspectartifact_missing) and Deployer task graph, followed byapply_deploymentwith the exact plan. Source mode resolves and deploys its reviewed commit directly.Use
list_releases;plan_rollback_deployment/rollback_deploymentwith the exact plan and displayed confirmation; deployment-scoped Artisan tools;deployment_process_status; anddiagnose_deploymentfor operations.Use
plan_promotion/promote_deploymentto deploy the exact current source commit or live artifact from one compatible Deployment to another. Artifact promotion reads verified release metadata and never contacts the Build Target. The destination source is pinned only after success.Use
plan_remove_deployment/remove_deploymentfor explicit cleanup.
For an artifact-mode staging or production Deployment, plan_start_rollout / start_rollout
prepares a separately health-checked candidate at guaranteed 100/0 stable/candidate traffic.
Inspect it with inspect_rollout or gimme://deployments/{name}/rollout. Preparation reserves one
temporary Target slot, is retryable after interruption, never runs migrations or candidate
background processes, and blocks ordinary deploy/promotion/rollback/update/removal until the
Rollout is completed or reversed. Shift reviewed traffic with plan_rollout_weights /
apply_rollout_weights; weights assign new cookie-accepting cohorts and are not an instantaneous
global request percentage. Existing signed cohorts stay sticky while their backend is nonzero and
healthy, and failed transitions restore the prior route before desired weights can change.
At 0/100, plan_complete_rollout / complete_rollout promote the candidate and hand off
background ownership; plan_reverse_rollout / reverse_rollout restore stable from any
recoverable phase. Both release temporary capacity only after verified Target cleanup.
See Build once and deploy an Application Artifact for migration, IAM separation, publishing, multi-Target deployment, promotion, rollback, reproducibility failures, costs, and retention boundaries. See Artifact Rollout acceptance evidence for the zero-cost operator scenario, failure matrix, and parent-criterion traceability.
Laravel candidate probes run inside the release before activation. Live HTTPS probes
run after activation and automatically restore the prior release if any live probe
fails. Each probe has a stable name, a bounded absolute path, and explicit phases
chosen from candidate and live; applications and deployments can add probes to the
primary inherited or overridden health definition. diagnose_deployment reports only
secret-safe states, numeric log metadata and HTTP statuses—never log content or decrypted
values. Queue workers use queue:restart; Horizon uses horizon:terminate, matching
Laravel's graceful restart model and avoiding a PHP-FPM reload.
MCP surface
Read-only resources:
gimme://stategimme://fleetgimme://operationsgimme://targets/{name}gimme://applications/{name}gimme://applications/{name}/artifacts/{build_id}gimme://provider-accounts/{name}gimme://secret-stores/{name}gimme://artifact-stores/{name}gimme://resources/{name}gimme://aws-networks/{name}/valkey-optionsgimme://deployments/{name}gimme://operations/{correlation_id}
list_operations and the operation resources expose a separate append-only audit
journal. It contains bounded object names, plan and correlation IDs, timestamps, phases,
classified outcomes, and safe error codes. Definitions, command arguments and output,
environment values, secret references, and exception text are never recorded.
See docs/reference/mcp.md for the complete tool and resource
catalog. Runtime schemas returned by tools/list, resources/list, and
resources/templates/list remain authoritative.
Current scope
Gimme provides the multi-target foundation, local SOPS, bounded AWS Secrets Manager stores, versioned S3-compatible Artifact Stores, deterministic Laravel artifact publication with Composer plus npm, pnpm, Yarn, or Bun and protected build-only secrets, and multi-Target artifact deployment with existing health-gated activation and automatic live rollback. Artifact and source promotion reuse the current live release without rebuilding, and content-addressed rollback verifies retained source or artifact releases before activation. Traffic splitting and fleet scheduling remain future work rather than implied production guarantees.
Resource provider and module coverage:
Resource module | Local (target-local) | AWS (managed) | Completion and next boundary |
PostgreSQL | ✅ | ✅ RDS PostgreSQL | Available. Registration, provisioning, reviewed updates, Deployment bindings, credential rotation, Recovery Point capture, detach/reactivate, guarded purge, retained tombstones, destruction, and drift inspection. Scheduled capture, in-place restore, major upgrades, and cross-Network/region moves remain separate work. See ADR 0008. |
Valkey | ✅ | ✅ ElastiCache Valkey | Available, AWS live validation pending. Provisioning, reviewed updates, typed Laravel bindings, inspection/drift, snapshots/restore, retention-by-default cleanup, destruction, and credential rotation. The AWS calls have so far been exercised with botocore stubs, not a live account. See ADR 0009. |
MySQL | — | — | Planned. A precise MySQL Resource contract; target-local and managed-provider implementations are separate slices. |
MariaDB | — | — | Planned. A precise MariaDB Resource contract, distinct from MySQL despite protocol compatibility; Amazon RDS for MariaDB is a candidate managed implementation. |
Memcached | — | — | Planned. Ephemeral-cache Resource contract, intentionally distinct from Valkey. |
DynamoDB-backed cache | — | — | Planned (AWS). Bounded table, TTL, region, and workload-identity contract; not an alias for Memcached or Valkey. |
Meilisearch | — | — | Planned. Bounded search Resource contract rather than a generic package installation. |
Application object storage | — | — | Planned. Application-facing binding; distinct from the available Artifact Store and Backup Destination contracts. |
SQS-compatible queue | — | — | Planned. External queue binding. Database- and Valkey-backed Laravel workers are already supported through current Deployment process behavior. |
✅ means the provider/module has a supported schema and content-addressed plan/apply workflow. Planned records direction only; it is not an implementation commitment. Gimme never exposes a provider's entire API: every module remains a bounded contract with derived ownership and no arbitrary provider configuration.
See docs/how-to/use-aws-rds-postgresql.md and
docs/how-to/use-aws-elasticache-valkey.md for
the implemented AWS provider boundaries.
Development
# From the repository root:
bash scripts/gimme-verifyThe project is licensed under the MIT License.
Available Tools
12 toolsdeploy_appDeploy applicationA
Deploy a registered application from Git using its pinned Deployer recipe. Requires the current plan_id and may run framework migrations defined by that recipe.
Inputs: name (required), plan_id (required). Returns: object
inspect_hostInspect hostARead-onlyIdempotent
Inspect the configured Ubuntu host and report its OS, installed runtime commands, service states, and non-interactive sudo availability. Makes no changes.
Inputs: no named parameters. Returns: object
list_appsList applicationsARead-onlyIdempotent
List locally registered PHP applications and their Git repository, framework recipe, branch, and computed deployment path. Does not contact the host.
Inputs: no named parameters. Returns: object
list_releasesList application releasesBRead-onlyIdempotent
List retained releases for a registered application and identify the current release. Makes no changes.
Inputs: name (required). Returns: object
plan_app_resourcesPlan application resourcesARead-onlyIdempotent
Plan a registered application's PostgreSQL database, database role, Valkey namespace, and protected remote environment file. Makes no changes.
Inputs: name (required). Returns: object
plan_deployPlan application deploymentARead-onlyIdempotent
Return Deployer's task execution plan for a registered application. Makes no remote changes and returns the current application plan_id for deploy_app.
Inputs: name (required). Returns: object
plan_stackPlan stack provisioningARead-onlyIdempotent
Resolve every desired package against the configured host's current package metadata and return an exact provisioning plan. Unavailable packages make the plan unready. Makes no changes and returns a plan_id for provision_stack.
Inputs: no named parameters. Returns: object
provision_app_resourcesProvision application resourcesAIdempotent
Create a registered application's PostgreSQL database and role, generate its password on the host, and write PostgreSQL and Valkey settings to shared/.env. Requires a matching plan from plan_app_resources.
Inputs: name (required), plan_id (required). Returns: object
provision_stackProvision stackAIdempotent
Apply a previously returned stack plan to the configured host. Installs missing APT packages and enables PostgreSQL and Valkey; rejects stale or invented plan IDs.
Inputs: plan_id (required). Returns: object
register_appRegister applicationAIdempotent
Register or update a PHP application's allowlisted deployment definition. Changes only the local registry; it does not connect to or modify the host.
Inputs: name (required), repository (required), branch, frontend, +1 more. Returns: object
rollback_appRollback applicationADestructive
Roll a registered application back to its previous good Deployer release. Changes the live current symlink and marks the replaced release as bad.
Inputs: name (required), confirmation (required). Returns: object
service_statusGet service statusARead-onlyIdempotent
Report systemd status for PostgreSQL, Valkey, or Caddy on the configured host. The service name is restricted to this allowlist and no changes are made.
Inputs: service (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource and action: host inspection, stack planning/provisioning, app registration, app resource planning/provisioning, deployment, releases, rollback, and service status. The plan/provision pairs are clearly separated by their plan/resource names and descriptions, so an agent should not confuse them.
Tool names follow a mostly consistent verb_noun snake_case pattern such as plan_stack, provision_stack, list_apps, deploy_app, and rollback_app. The only outlier is service_status, which uses a noun_noun form instead of a verb-first convention, but it is still readable and not confusing.
Twelve tools is well-scoped for a provisioning and deployment server. Each tool covers a meaningful step in the workflow, and none feel redundant or unnecessary.
The tool set covers the main lifecycle well: inspect, plan, provision, register, deploy, list releases, rollback, and check service status. The main gap is the lack of teardown or removal operations, such as unregistering an app or dropping provisioned resources, but most core workflows are fully supported.
Maintenance
Related MCP Connectors
Manage PHP apps on your own Ubuntu servers: deploy, roll back and inspect Laravel and WordPress
Deploy services, add databases, run agents, read logs, check vulnerabilities and publish pages.
Deploy apps to servers you own: projects, deployments, logs, health and pull request previews.
Deploy and manage sites, databases, files and more on Prostack Cito servers.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables SSH-based deployment operations such as git pull, command execution, script upload/run, and SSH config management.4-
- AlicenseAqualityCmaintenanceEnables MCP clients to inspect and manage a Dokku host over SSH with structured tools, read-only defaults, and explicit guardrails for safe operations.10MIT
- AlicenseAqualityAmaintenanceEnables Codex or Claude users to deploy applications and Compose services, inspect logs/databases/backups, patch environment variables, and manage Cloudflare DNS records and HTTPS domains through natural-language conversations, running locally with user-supplied credentials and preview/read-only safeguards.9MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to inspect and safely operate a Linux VPS through typed DevOps tools governed by YAML allowlists, read-only defaults, dry-run plans, secret redaction, and tamper-evident auditing.MIT