Enables AI agents to build, start, check, and fix local multi-service application stacks with a single command.
Also known as flisk-sh/flisk, @flisk-sh/flisk
- Stars
- 49
- Tools
- 23
- Downloads, 30 days
- 33,691
- Latest version
- 1.4.56
- Last commit
- Nov 15, 2026
- License
- MIT
What is Flisk MCP?
Flisk enables AI agents to build, start, check, and fix local multi-service application stacks with a single command. It exposes 23 tools, such as doctor, up, down.
Summary generated from the project's README
About Flisk MCP server
Developers looking to orchestrate multi-service applications locally can use Flisk to build, start, and manage entire stacks with a single command. It allows for the creation of complex environments including APIs, websites, workers, and databases by using a simple service.json configuration for each component. This approach automates the generation of Dockerfiles, Compose files, and gateway routes, ensuring all parts are wired together with correct environment variables like DATABASE_URL.
Users can choose to run small applications as plain local processes without Docker, or use Docker and Tilt for larger stacks that require live reloading and containerization. The tool supports importing existing docker-compose.yml files to convert them into the Flisk format. For those using AI-driven development, the flisk mcp command provides 23 specific tools to allow agents to manage the local development lifecycle directly.
What you can do with it
- 1Initialize a new multi-service projectAn AI agent can generate a complete application structure by answering configuration questions through the command line.
- 2Convert existing Docker Compose setupsYou can transform an existing docker-compose.yml file into a Flisk-managed project to gain automated routing and health checks.
- 3Run a full stack locallyStart all services, including databases and gateways, using a single command to get a working environment immediately.
- 4Enable AI-driven local developmentProvide an AI assistant with the necessary tools to interact with and manage your local service stack.
Written from the project's README. Every use case is checked against a quote from it.
How to install Flisk MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Flisk MCP in Claude Code
$ claude mcp add flisk -- npx -y @flisk-sh/flisk mcpInstall Flisk MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"flisk": {
"command": "npx",
"args": [
"-y",
"@flisk-sh/flisk",
"mcp"
]
}
}
}Install Flisk MCP in VS Code
.vscode/mcp.json
{
"servers": {
"flisk": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@flisk-sh/flisk",
"mcp"
]
}
}
}Install Flisk MCP in VS Code CLI
$ code --add-mcp '{"name":"flisk","type":"stdio","command":"npx","args":["-y","@flisk-sh/flisk","mcp"]}'Install Flisk MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"flisk": {
"command": "npx",
"args": [
"-y",
"@flisk-sh/flisk",
"mcp"
]
}
}
}Install Flisk MCP in Codex
$ codex mcp add flisk -- npx -y @flisk-sh/flisk mcpInstall Flisk MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.flisk] command = "npx" args = ["-y", "@flisk-sh/flisk", "mcp"]
Install Flisk MCP in Gemini CLI
$ gemini mcp add -s user flisk npx -- -y @flisk-sh/flisk mcpInstall Flisk MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"flisk": {
"command": "npx",
"args": [
"-y",
"@flisk-sh/flisk",
"mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @flisk-sh/flisk 1.4.56 in an isolated container with no network and no keys. It answered and listed 23 tools.
Flisk MCP tools 23
Read from the server with tools/listdoctorRead-onlyCheck whether this machine can run the Flisk stack (Docker, Tilt, ports). Read-only. Optionally set projectPath to include checks for a specific Flisk project. Returns data.ready and data.host.canUp; run it before `up`. For the state of a running stack use `status`; for whether generated files are consistent use `config_verify`.
upActionStart the stack (or part of it) detached from the optional projectPath and return without waiting for it to be ready. Poll `status` for data.tilt.readiness.ready. Fails fast on an unknown service, an unsupported host, or a Tilt already running.
downActionStop the running stack, optionally selecting its project with projectPath. It stops the running services and does not edit the project's files. Use `status` first to see whether a stack is running, set dryRun to preview, and start it again with `up`.
statusRead-onlyShow the live state of the stack: its stacks, resources, their ingress URLs and container ports, the stack-level ports, and Tilt readiness (data.tilt.readiness: ready, pending, failures, enabled; null when no Tilt answers). Read-only. Poll it after `up`. For the services a project defines whether or not they run use `resource_list`; for URLs only use `network_list`; for host checks use `doctor`. Optionally select the project with projectPath.
logsRead-onlyA bounded snapshot of recent logs from the running stack (default the last 200 lines, at most 10000), returned as text. Read-only. Optionally select the project with projectPath. Not a stream: call it again for newer lines. Use `status` first to find which service is failing, then pass services to narrow the output.
resource_listRead-onlyList the selected project's services (resources) with their stack, type and port, whether or not they are running. Read-only. Use `status` for live state, `stack_list` to group them by stack and `agent_list` for agents only. Set projectPath when the MCP server is not running from the project root.
resource_restartActionRestart one running resource in the stack (or trigger its rebuild); the other resources are not touched. It needs a running stack: start one with `up`. Names come from `resource_list`. Set projectPath when the MCP server is not running from the project root.
resource_runActionRun a one-off command (a seed script, a status check, printenv) with the environment one resource has in the stack, and return its exit code, stdout and stderr (the last 64 KB of each). A container resource must be running (start it with `up`); a local-process resource runs from its folder. No input is passed. Names come from `resource_list`. Set projectPath when the MCP server is not running from the project root.
agent_listRead-onlyList AI agent resources (appType: 'agent') in the project with their stack, runtime, durability and port. Read-only. Use `resource_list` for every resource type, and `agent_sessions` to inspect one agent's sessions. Set projectPath when the MCP server is not running from the project root.
agent_sessionsRead-onlyList the sessions of a running AI agent resource (id, last activity, status, checkpoint size), or read one session's checkpoint when sessionId is set. Set projectPath when the MCP server is not running from the project root.
stack_listRead-onlyList the project's stacks with their resource counts. Read-only. Use `resource_list` for the resources themselves. Set services to include each stack's service names, and verbose for its description. Set projectPath when the MCP server is not running from the project root.
project_infoRead-onlyProject root, whether the generated master files exist (data.configured, data.missingFiles), and resource and stack counts. Read-only; a quick first call to learn whether a folder is a configured Flisk project. Use `config_verify` to check that the generated files match, and `status` for the running stack. Set projectPath when the MCP server is not running from the project root.
Show all 23 toolsShow fewer tools
project_templatesRead-onlyList the starter templates project_init can clone (data.templates): each one's key, repo, description and, for a template pinned to a commit, the ref it checks out. Read-only; the same rows as `flisk project --list --json`. Pass a key as project_init's template.
network_listRead-onlyThe Traefik URL of every frontend and API service, with its base path, port and whether it answers (running, stopped). Read-only. Use it to find where to open a service; use `status` for full readiness. Set projectPath when the MCP server is not running from the project root.
config_verifyRead-onlyCheck that the generated files match .flisk/project.json and that every service.json is valid. Returns data.valid, data.errors, data.warnings and data.diffs; a drifted generated file is fixed with config_regenerate. Set projectPath when the MCP server is not running from the project root.
config_explainRead-onlyExplain one project file: whether Flisk generated it or the user owns it, its source, whether it is edited now, whether editing it blocks `up`, and what to edit instead. Run it before editing a file you did not write. Set projectPath when the MCP server is not running from the project root.
runtime_checkRead-onlyRead-only. Check that the installed Flisk CLI has its bundled runtime assets (engine, templates). Returns ok, assetRoot and what is missing; a source checkout reports ok: false because the assets exist only in a packaged install. projectPath is optional: a project-local install under its node_modules is checked too.
config_regenerateActionRegenerate the master config files in .flisk/.flisk-out/ from .flisk/project.json. A dry run by default, which returns the planned changes as text; set dryRun to false to write them, which discards hand edits in those generated files. Set projectPath when the MCP server is not running from the project root.
resource_createActionScaffold a new service (service.json, Dockerfile, source and a test) with `flisk resource <name> --yes`, or register an existing directory that already has a service.json. Returns the command's text output. Without stack it uses the only existing stack or `main`, and fails when several stacks exist. Do not call it again for a resource that already exists: that rewrites its service.json and can assign it a new port (check with resource_list first). Call `up` afterwards to start it. Set projectPath when the MCP server is not running from the project root.
stack_assignActionAssign resources that have no stack yet to a stack (writes `stack` into their service.json). A resource already in a stack is refused. Returns the command's text output. Set projectPath when the MCP server is not running from the project root.
project_initActionCreate a Flisk project with `flisk project --yes`: in projectPath (an existing directory; default the server's directory) write .flisk/project.json and generate its files, or, with template, clone a starter project into a new directory there (then call project_init again with projectPath set to the clone to configure it). Inside an existing project it refreshes that project's generated files instead and never overwrites its project.json. Returns the command's text output.
project_ejectActionWrite EJECTED.md with `flisk eject --json`: it lists the generated Tilt files and how to run the stack with plain Tilt, and copies, moves or deletes nothing. It changes the project, so it is refused unless confirm is true; dryRun returns the plan (data.generatedFiles, data.created) without confirm. Set projectPath when the MCP server is not running from the project root.
project_importActionImport the services in a directory's root docker-compose.yml as bring-your-own service.json files with `flisk import --json`, which runs the pinned flisk-import from npm (the first run needs network access). It writes without asking: set dryRun to get the plan only, and force to overwrite an existing service.json. Returns data.written and the importer's output. Set projectPath when the MCP server is not running from the project root.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableflisk-sh/flisk is public and reachablegithub.com/flisk-sh/flisk ↗Pass
- Package names this repository as its source@flisk-sh/flisk names flisk-sh/flisk as sourcenpmjs.com/package/@flisk-sh/flisk ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @flisk-sh/flisknpmjs.com/package/@flisk-sh/flisk/v/1.4.56#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/flisk-sh/flisk ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 8.3 / 10; weakest: Maintained 0, Branch-Protection 3scorecard.dev/viewer/?uri=github.com/flisk-sh/flisk ↗Pass
- Package name not close to a popular packageNo popular package one edit away from @flisk-sh/fliskPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model23 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFlisk: local development for multi-service apps, started with one command
What is Flisk? · Key features · Quick start · Commands · Configuration · With your AI agent · FAQ · Docs
👋 Welcome · 欢迎 · 歡迎 · ようこそ · 환영합니다 · Bienvenue · Bienvenido · Bem-vindos · Willkommen · Benvenuti · Bun venit · أهلًا · Hoş geldiniz · Ласкаво просимо · Witamy · خوش آمدید · Selamat datang · Chào mừng · ยินดีต้อนรับ · Καλώς ήρθατε · സ്വാഗതം
What is Flisk?
Flisk is a command-line tool for local development. It runs every part of your app (API, website, workers, AI agents, database) on your computer with one command. Docker is optional: a small app runs as plain local processes, and a bigger one gets containers, one address in front of every part and live reload on Docker and Tilt. Have a docker-compose.yml? flisk import reads it. Otherwise describe each part in a small service.json; for the Docker path Flisk writes the Dockerfiles, the Compose file and the Tiltfile from it, and keeps them in sync. An MCP server lets your AI agent run it too. It does not deploy: production stays with your own tools.
Try it first. One command, nothing to install except Node.js 22.12+, and no Docker needed:
npx @flisk-sh/flisk demo
With Docker running and Tilt installed, that starts the full restaurant demo: six services, Postgres, one gateway and live reload. Without them (or on native Windows), it starts a small menu app as two local processes in about a second and opens it in your browser. You should see the menu at http://localhost:3000, with its API answering at http://localhost:4000/api/menu. flisk down in the demo folder stops either one.
On Windows, the full app runs in Ubuntu on WSL2: follow Start here on Windows.
Want to choose your own stack? Answer a few questions with the arrow keys and Enter, and Flisk writes a project that runs:
npx @flisk-sh/flisk create
It offers every website framework, API language and starter that Flisk's generators know, read from the generators themselves (type to filter a long list), and the default runs on your computer with no Docker, no Tilt and no database: it writes a website and an API with the real flisk resource --local command, then you npm install in each and run flisk up. Pick "I know what I want: let me choose every part" to choose the framework and language yourself, or to add a worker, a queue (NATS, RabbitMQ), Redis, Qdrant, MinIO or an AI agent (those run with Docker and Tilt). The project name comes last and Enter takes my-app; a review shows what will be created and which programs it needs before anything is written. Add --dry-run to see the commands it would run, or flags such as --frontend vue --backend fastify --yes to skip the questions in a script.
Want a website, an API and a Postgres database that already work together? npx @flisk-sh/flisk create myapp --starter next-postgres (or flisk project next-postgres --path myapp) writes a Next.js page with an add, tick and delete list, an Express API and a migrator that creates and seeds the table; then cd myapp && flisk up. It needs Docker.
Install Flisk with npm install -g @flisk-sh/flisk, then, in a new folder:
mkdir my-shop && cd my-shop
flisk project --yes
flisk resource orders-api --type backend --stack shop --yes
flisk resource shop-web --type frontend --stack shop --yes
flisk up shop
That starts an orders API and a storefront behind one gateway, with Postgres and live reload, and prints their URLs. It needs Docker, Tilt, Node.js 22.12+ and Bun 1.2+; flisk doctor says what is missing. A small app can skip Docker and run as local processes.
Two ways in: flisk project starts a new app from scratch (above); flisk import starts from an app you already have. Already have a Compose file? npx @flisk-sh/flisk import . && npx @flisk-sh/flisk up (add --dry-run to import to preview).
One small file per service
flisk resource wrote a service.json for each part. This is the whole file for the orders API, and the only configuration you edit for it:
{
"$schema": "https://flisk.sh/schema.service.json",
"schemaVersion": 1,
"appName": "orders-api",
"appType": "backend",
"stack": "shop",
"port": 4000,
"healthCheckPath": "/health"
}
From it Flisk writes the Dockerfile, the Compose entry, the gateway route, the health check and the DATABASE_URL, and refuses to start if one of those files was edited by hand. Every field · Everything Flisk writes
Already have a docker-compose.yml?
flisk import . writes one service.json per Compose service and keeps its ports, names and env values:
flisk import .
flisk up
On Windows: a Compose app runs its services as containers, so do both steps inside Ubuntu on WSL2, not in PowerShell. Clone the app into your Ubuntu home folder (~/, not /mnt/c or D:\), turn on Docker Desktop's WSL integration for Ubuntu, and install Node and Tilt in Ubuntu: Start here on Windows.
A plain Compose app (a Node API and Postgres) answered through Flisk's router 49 s after flisk import on a clean Ubuntu CI runner, images pulled and built from scratch, install not counted (run, claims). CI repeats it on every pull request.
Rather ask your AI helper? It runs these commands for you: copy a prompt. Never written code? Start here, step by step · Words you'll see
Key features
- One
service.jsonper service. Flisk generates the Dockerfile, the Compose entry, the Traefik routes, the health check and the Tiltfile from it. You do not hand-write adocker-compose.ymlornginx.conf. - One command, one address.
flisk upstarts Postgres, your services and a local gateway, starts services in health-checkeddependsOnorder, and prints a*.localhostURL for each. - Hot reload while you code. Tilt live-updates a container when you save its files; there is no rebuild step.
- Wired for you.
DATABASE_URL, the API URL your frontend calls, and missing secrets such asJWT_SECRETare generated and injected, never copied by hand. - Generated files you can check. Flisk records what it wrote, refuses to start when a generated file was edited by hand, and
flisk config verifyreports drift (generated files and drift checks). - Built for AI helpers.
flisk mcpgives Claude Code, Codex, Cursor and other agents 23 tools, andflisk projectadds the Flisk skills and anAGENTS.md. - Runs AI agents too. Agent services get durable checkpoints, sticky
x-session-idrouting, and/healthand/readychecks (below). - No Kubernetes; no Docker for small apps. Docker and Tilt run the stack without a local cluster such as kind or minikube, and services that each declare a
commandrun as plain local processes. - Quick to start. With warm image layers, a one-backend stack is healthy in 12.8 to 13.8 seconds (timing notes). An 8-service stack settles in 32 to 42 seconds warm and about 4.5 minutes on its first cold build (benchmark).
- Free core. The CLI is MIT and needs no key to run
flisk up; Premium extras are optional (license matrix).
Is Flisk right for your team?
Not sure Flisk fits? Answer three questions for a plain-English score and the reasons behind it, or use the calculator on flisk.sh.
Trusted by
Use Flisk with your AI agent
AI helpers are good at writing the app and bad at the setup around it: every time one rewrites a Dockerfile, a Tiltfile or an nginx.conf by hand, something breaks, and you pay in time and tokens to fix it. Flisk writes that setup the same way every time, so you and your helper stick to the app.
Install Flisk, then paste the prompt into Claude Code, Codex, Cursor or any other AI helper that can run commands:
npm install -g @flisk-sh/flisk
Build me a small online shop with a storefront and an orders API, and run it on my laptop with Flisk.
The helper creates the project, adds each part and starts it, then gives you the links to open. If something is missing, flisk doctor says what, in plain words.
Add a service to a project you already have
Use Flisk to add a backend service called payments-api to my shop stack, then start the stack and give me the URLs.
Build an AI agent with tools and a database
Use Flisk to scaffold an AI agent, an MCP tools server, and a database in one stack called shop, then start it and tell me how to talk to the agent.
Something is not working
Run flisk doctor, explain every problem in plain words, and fix what you can. Then start my stack with flisk up.
See what is running
Use flisk status to tell me which services are running, which are unhealthy, and what URL each one has.
Stop everything
Stop my Flisk stack with flisk down and confirm nothing is left running.
Pick your agent
Each helper installs a little differently; pick yours for the exact steps. Already have a project? flisk connect claude (or cursor, codex) adds the flisk mcp server (23 tools) and the Flisk skills where that agent reads them; add --dry-run to see the files first. What the agent can then do: Flisk for AI agents.
curl -fsSL https://claude.ai/install.sh | bash
npm install -g @flisk-sh/flisk
Then start Claude Code by typing claude in your project folder, and paste the prompt above. For developers: flisk project writes the Flisk skills to .claude/skills/, which Claude Code loads. To let Claude Code drive Flisk through MCP tools, run claude mcp add --scope project flisk -- flisk mcp. Windows install, the .mcp.json file and the AGENTS.md tip: full Claude Code setup.
Any other agent that can run terminal commands works too: point it at AGENTS.md, or connect it to flisk mcp, which runs an MCP server over stdio. flisk project adds the Flisk skills (build a stack, recipes for a shop, a SaaS, an AI agent and a blog, doctor, up, resource, status, troubleshoot; source in .agents/skills) and an AGENTS.md to your project, so the agent checks your setup and explains failures instead of guessing at Docker or Tilt configuration. More prompts by category are in the prompt gallery.
No terminal at hand? Open the Flisk starter in GitHub Codespaces or Gitpod, or pick another one-click option.
Run your AI agents next to your services
Flisk is the local runtime for agent systems: the agent, its MCP tools, its database, its queue, behind one gateway, one command.
# Scaffold an agent, an MCP tools server, and a database in one stack
flisk resource bot --type agent --stack shop --yes
flisk resource tools-mcp --type mcp --stack shop --yes
flisk up shop
Agents get durable checkpoint volumes that survive flisk down, sticky session routing via x-session-id, graceful SIGTERM drain during hot reloads, a Docker health check on /health, and application-level readiness checks on /ready. See the AI agents guide and honest comparison with agent frameworks.
Prerequisites (install once)
| Tool | Version | Install | Needed for |
|---|---|---|---|
| Your app's runtime | whatever your app uses | Node.js, Python, Go, Bun, ... | Every path: it runs your code |
| Node.js | 22.12+ | nodejs.org | npm install (npm install -g @flisk-sh/flisk) |
| Docker | Engine 25+, Compose 2.20.2+ | docker.com | Docker + Tilt path only |
| Tilt | 0.25+ | curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash |
Docker + Tilt path only |
| Bun | 1.2+ | curl -fsSL https://bun.sh/install | bash |
Bun install (bun add -g @flisk-sh/flisk), or generated JavaScript services |
Two ways to run. A project whose services each declare a
commandruns them as local processes: you need only Flisk and your app's runtime (simplest path). A database, one gateway URL for every service, or the same container you deploy need Docker and Tilt.flisk doctorchecks only what your project uses.
Set up your machine. Pick your system:
Get your Mac ready once. Paste each grey box into the terminal (press Cmd+Space, type Terminal, press Enter) and press Enter.
1. Node.js 22.12+ from nodejs.org, plus your app's own language if it is not JavaScript. That is all a small app needs: the simplest path.
2. Only for bigger apps (a database, one address in front of every part, or the same container you deploy): start Docker Desktop, OrbStack or Colima, and install Tilt:
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh \
| bash
3. Install Flisk and check your Mac:
npm install -g @flisk-sh/flisk
flisk doctor
flisk doctor checks only what your project uses and prints a fix for anything missing. Full steps: macOS setup.
Installation
Install the CLI with npm, with Bun, as a prebuilt binary that needs no Node.js or Bun, or run it from its container image:
npm install -g @flisk-sh/flisk
This downloads Flisk with npm, which comes with Node.js 22.12+. Check it with flisk --version: it prints a version number. Update later with flisk upgrade. Pinning a version and uninstalling: install with npm.
For developers: public npm is the recommended default; to install through GitHub Packages instead, configure registry authentication as described in GitHub Packages installation.
Update later with flisk upgrade (or its alias flisk update), or npm install -g @flisk-sh/flisk@latest. To pin a version or read what changed, see upgrading and version pinning.
[!IMPORTANT] Get Flisk from the flisk-sh/flisk repository, the
@flisk-sh/flisknpm package, or the official website. Follow the installation links from these official sources. A similar repository name or copied README does not establish that a download is official.
Quick start
The commands under What is Flisk? are the whole quick start, once the prerequisites are in place. This section is the long version: the other ways to start, what to expect, and what Flisk writes. Never used a terminal? Start here instead.
Flisk MCP questions
How do I add Flisk MCP to Claude Code?
Run claude mcp add flisk -- npx -y @flisk-sh/flisk mcp in your terminal. Add --scope user to make it available in every project.
How do I add Flisk MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Flisk MCP provide?
It exposes 23 tools, including doctor, up, down, status, logs.
Does Flisk require Docker?
Docker is optional; small applications can run as plain local processes, while larger ones use containers.
Can I use Flisk with an existing docker-compose file?
Yes, you can use the import command to read an existing Compose file and create service configurations from it.
How does Flisk work with AI agents?
Flisk provides an MCP server that gives AI agents like Claude Code or Cursor 23 specific tools to manage the stack.
What operating system is required for Windows users?
On Windows, the full application stack runs within Ubuntu on WSL2.