appsmith-mcp

MCP server for a self-hosted Appsmith instance, over Appsmith's own REST API — the same API the editor uses.

Built because no reliable Appsmith MCP server exists: there is nothing published on npm or PyPI, nothing in the appsmithorg GitHub org, and the listings that surface in search results are auto-generated stubs with no implementation behind them.

How it authenticates

Appsmith uses Spring Security form login behind CSRF protection:

1. A GET /api/v1/users/me seeds an XSRF-TOKEN cookie.
2. POST /api/v1/login sends username/password form-encoded, echoing that token in the X-XSRF-TOKEN header.
3. The response sets a SESSION cookie used for every later call.

The client logs in lazily on first use and re-logs in once automatically on a 401, so an expired session heals itself instead of failing a tool call.

Setup

npm install
cp .env.example .env         # then put your Appsmith password in .env
npm run check                # read-only checks against the live instance
npm run check -- --scratch   # also covers writes, via a throwaway app it deletes

npm run check prints a PASS/FAIL row per endpoint — run it whenever an Appsmith upgrade might have moved routes. --scratch creates an mcp-smoke-* application, exercises create-page / publish / delete against it, and removes it again.

Registration

Registered at user scope, so it is available in every project rather than one:

claude mcp add appsmith --scope user -- \
  node --env-file-if-exists=<abs-path>/.env <abs-path>/src/index.js

That writes to ~/.claude.json. Paths must be absolute — a user-scope server is launched from whatever directory the session happens to be in.

Credentials are read from .env via Node's --env-file-if-exists, so no secret lives in the MCP config. Because .env pins one instance, retarget it by changing APPSMITH_URL.

To scope it back to a single project, claude mcp remove appsmith --scope user and put the same command in that project's .mcp.json.

Tools

Read

Tool	Endpoint
appsmith_whoami	GET /api/v1/users/me
appsmith_list_workspaces	GET /api/v1/workspaces/home
appsmith_list_applications	GET /api/v1/applications/home
appsmith_list_pages	GET /api/v1/pages/application/{id}
appsmith_get_page	GET /api/v1/pages/{id}
appsmith_list_queries	GET /api/v1/actions
appsmith_list_js_objects	GET /api/v1/collections/actions
appsmith_list_datasources	GET /api/v1/datasources
appsmith_get_datasource_structure	GET /api/v1/datasources/{id}/structure
appsmith_list_plugins	GET /api/v1/plugins
appsmith_search_entities	GET /api/v1/search-entities
appsmith_export_application	GET /api/v1/applications/export/{id}

Edit — changing an existing app's logic

Tool	Endpoint
appsmith_update_query	PUT /api/v1/actions/{id}
appsmith_create_query	POST /api/v1/actions
appsmith_update_js_object	PATCH /api/v1/collections/actions/{id} + PUT .../body
appsmith_create_js_object	POST /api/v1/collections/actions
appsmith_delete_query	DELETE /api/v1/actions/{id} — gated
appsmith_delete_js_object	DELETE /api/v1/collections/actions/{id} — gated
appsmith_get_widget	GET /api/v1/pages/{id} (one widget)
appsmith_update_widget	PUT /api/v1/layouts/{layoutId}/pages/{pageId}
appsmith_clone_widget	PUT /api/v1/layouts/{layoutId}/pages/{pageId}
appsmith_generate_crud_page	POST /api/v1/pages/crud-page

Write — structure and lifecycle

Tool	Endpoint
appsmith_create_workspace	POST /api/v1/workspaces
appsmith_create_application	POST /api/v1/applications
appsmith_create_page	POST /api/v1/pages
appsmith_execute_query	POST /api/v1/actions/execute
appsmith_publish_application	POST /api/v1/applications/publish/{id}
appsmith_clone_application	POST /api/v1/applications/clone/{id}
appsmith_delete_application	DELETE /api/v1/applications/{id} — gated
appsmith_api_request	any route; non-GET gated

Editing is deliberately typed rather than left to appsmith_api_request: the raw tool is gated behind ALLOW_DESTRUCTIVE and cannot be safely auto-approved, since it can reach any endpoint. The typed tools each do one thing, so they can be allow-listed individually.

appsmith_update_query sends only the fields you pass — the server merges the rest, so the datasource and untouched settings survive. It deliberately does not rename: renaming needs a refactor pass that rewrites bindings across the app, and a plain PUT would leave every reference broken.

Adding widgets

There is deliberately no "create widget from scratch" tool. Appsmith's widget defaults live in its frontend, not its API — /api/v1/widgets, /widget-config and /configs all 404 — and a real widget carries 24–65 properties depending on type. A hand-written defaults catalogue would replicate frontend logic, drift on every Appsmith upgrade, and fail silently when it did. The two supported routes instead:

• appsmith_clone_widget copies a widget that Appsmith itself created, so the defaults are always correct and there is nothing to maintain. Every descendant gets a fresh widgetId and a free name (Canvas1 → Canvas2, interno → interno1); names only need to be unique per page. The copy is placed below its siblings so it cannot land on another widget. Bindings inside the copy are not rewritten — one that referenced the source by name still points at the original, so the response returns renamedInsideCopy for the caller to fix.
• appsmith_generate_crud_page calls Appsmith's own generator for a whole screen.

Bindings

appsmith_update_widget maintains dynamicBindingPathList for you. Appsmith only evaluates {{ }} on properties listed there and the server does not infer it: a binding written without registration is stored verbatim and rendered as a literal string — which, for a boolean like isDisabled, is always truthy. Setting a binding adds the path; setting a literal removes it. A widget's other properties are preserved, since the whole layout is read, patched and written back.

Safety

• appsmith_delete_application and non-GET appsmith_api_request calls refuse to run unless APPSMITH_MCP_ALLOW_DESTRUCTIVE=true.
• appsmith_execute_query runs against the real datasource — a write query writes. It is not gated, since running queries is the point, so check what a query does before running it.
• Large payloads (page DSLs, exports) are truncated at APPSMITH_MCP_MAX_CHARS. appsmith_get_page returns a widget outline by default; pass full=true for the raw layout. appsmith_export_application takes an outputPath to write to disk instead of returning inline.

Instance quirks found while building this

Two behaviours differ from what the CE controllers suggest, both handled in the code:

• GET /applications/home documents workspaceId as optional, but this instance rejects the call without it. appsmith_list_applications fans out across every workspace when no id is given.
• POST /pages rejects an empty layouts array, and layouts: [{}] silently creates a page whose DSL is null — blank and unusable in the editor. The root CANVAS_WIDGET canvas must be sent explicitly; see src/defaults.js.

Maintenance

Routes were taken from the Appsmith backend controllers, not guessed:

• controllers/ce/ApplicationControllerCE.java
• controllers/ce/PageControllerCE.java
• controllers/ce/ActionControllerCE.java
• controllers/ce/DatasourceControllerCE.java
• controllers/ce/WorkspaceControllerCE.java
• constants/ce/UrlCE.java

Appsmith's API is not a documented public contract, so a major upgrade can move a route. npm run check is the fast way to find out.

License

MIT — see LICENSE.