Your client. Your Strapi.

Run Safe Strapi on your own machine or agent host. It reads your Strapi connection from a local environment file and talks directly to your CMS. No Safe Strapi account or shared access key is required.

1. Install the package

Install Node.js 22.5 or newer, then install the latest npm release. Native SQLite dependencies may require build tools if a prebuilt binary is unavailable for your platform.

npm install --global safe-strapi-mcp
safe-strapi-mcp --help

View on npm or review the source on GitHub. Releases are built from the public repository with npm provenance.

2. Connect your Strapi project

Add these variables to your private environment file. STRAPI_URL is your CMS URL, which may differ from your public website address. Paste your token after the equals sign in your local copy.

STRAPI_URL=http://localhost:1337
STRAPI_API_TOKEN=

Use a Strapi API token with find, findOne, create, and update permissions for the content types you intend to edit. Related media and content must be readable too. Keep this file out of version control.

Point the tool at the Strapi source directory containing src/api and src/components. It discovers collection types with Draft & Publish, a UID field, and a dynamic zone. Each discovered content type and zone appears in list_projects.

STRAPI_PROJECT_ROOT=/absolute/path/to/strapi
STRAPI_CONTENT_TYPE=page
STRAPI_BLOCKS_FIELD=blocks
STRAPI_SLUG_FIELD=slug
STRAPI_TITLE_FIELD=title
STRAPI_LOCALE=en

For an existing token variable such as MY_CMS_TOKEN, set STRAPI_TOKEN_ENV=MY_CMS_TOKEN. The tool reads that variable rather than requiring you to duplicate the secret.

3. Add it to your MCP client

Choose a local stdio server. Use the executable path returned by which safe-strapi-mcp on macOS/Linux or where safe-strapi-mcp on Windows. Set the arguments below using your own absolute paths.

{
  "mcpServers": {
    "safe-strapi": {
      "command": "/absolute/path/to/safe-strapi-mcp",
      "args": [
        "--env-file",
        "/absolute/path/to/strapi/.env",
        "--project-root",
        "/absolute/path/to/strapi"
      ]
    }
  }
}

Client configuration formats vary; the command and arguments stay the same. The MCP process loads the file itself, so the secret does not need to appear in your client configuration or chat. Restart your client after adding the server.

4. Start with a read-only test

Your AI client uses the environment file selected at setup. For another Strapi installation, add another named MCP server with its own file and source directory.

Continue with the prompt cookbook for copy-ready examples covering JSON input, component insertion, reordering, long pages, and production team workflows. Agents can fetch the same guide as raw Markdown from /prompts.md.

Available tools

list_projects, find_pages, inspect_page, list_components, get_component_schema, preview_clone_and_modify, clone_page_and_modify, inspect_owned_draft, modify_owned_draft, duplicate_component, replace_component, validate_draft, and compare_pages.

Operations support insertion, patching, moving, duplication, replacement, and removal on draft copies. API indexes are zero-based and operations run in order. Inspect the current order before selecting a block. Publish reviewed content yourself in Strapi.

What is supported?

Strapi 5 collection types with dynamic zones and Draft & Publish. Localhost and remote CMS URLs both work when reachable from the machine running the MCP. Single types, automatic publishing, and arbitrary unknown schemas are not part of the automatic setup.

If you only have a remote URL and token, request the schema files from the project owner, or supply a --config /absolute/path/projects.json file with embedded component and content-type schemas. A normal content API token does not provide the complete schema catalog.

The ownership and retry database is stored at .safe-strapi/audit.sqlite inside the selected project by default. Keep it private, preserve it between sessions, and add .safe-strapi/ to your gitignore. Deleting it removes the ownership records required to modify existing drafts.

Troubleshooting

CONFIG_ERROR: check the source directory and supported content types. TOKEN_MISSING: check the selected env file and token variable name. STRAPI_ERROR: check the CMS URL, permissions, and population rules. AMBIGUOUS_SELECTOR: specify an index or occurrence. SOURCE_CHANGED or DRAFT_CHANGED: inspect and preview again. DRAFT_NOT_OWNED: only drafts registered in this installation’s audit database can be modified. OPERATION_BUSY: another MCP process is writing; retry later. WRITE_OUTCOME_UNKNOWN: Strapi may have accepted a create whose response was lost; inspect the CMS through the API before starting a new operation.

Writes are serialized when clients share the same audit database. Strapi REST has no atomic revision precondition for external writers, so avoiding every possible GET/PUT race requires a Strapi-side conditional-update endpoint.

For an explicitly configured shared HTTP installation, the administrator supplies a separate MCP access key. That is an optional deployment mode, not a requirement for the local package.