> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Lovable MCP server (research preview)
> Connect AI agents and developer tools to Lovable using the Model Context Protocol. Build, iterate, and deploy apps programmatically.
The Lovable MCP server is in **research preview**, which means it is available for early experimentation and feedback but is not yet production-ready:
* Tool names, parameters, and response shapes **may change without notice**, including breaking changes
* Features may be added, changed, or removed based on feedback
## What is the Lovable MCP server?
Lovable exposes itself as a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server at `https://mcp.lovable.dev`. This lets AI clients (such as Claude Desktop, Cursor, and other MCP-compatible tools) manage your Lovable projects through natural language.
When connected, your AI agent can create projects, send messages to Lovable, inspect code, deploy apps, and more, all without leaving the client you're already working in.
This is different from [chat connectors (MCP servers)](/integrations/mcp-servers), which let the Lovable agent connect to your tools. The Lovable MCP server lets external agents connect to Lovable.
### What MCP is
MCP (Model Context Protocol) is an open standard that lets AI agents discover and call external tools. When an agent connects to an MCP server, it can see what tools are available and decide when to use them. Lovable's MCP server makes Lovable one of those tools: findable, invokable, and composable.
### The flow
1. An agent connects to the Lovable MCP server
2. The agent calls a tool (for example, `create_project`) with a description of what to build
3. Lovable builds the project and returns a preview URL.
4. You can open the preview, review what was built, and continue iterating by sending more messages
5. The agent keeps building as you refine, adding features, fixing issues, changing the design
6. When you're happy with it, publish with `deploy_project`. Or don't, publishing is always optional.
## Who this is for
* **Developers using AI coding assistants** (Claude Code, Cursor, Windsurf) who want to spin up and iterate on Lovable projects without leaving their editor
* **Agent builders** who want Lovable as a step in a larger agent flow: generate content, scaffold a UI, deploy it, and hand off the URL
## Why use the Lovable MCP server
* **Agent-driven development:** Let Claude, Cursor, or your own agent scaffold and iterate on Lovable projects using natural language.
* **Code inspection:** Read project files, diff changes, and browse edit history programmatically.
* **Cross-tool workflows:** Combine Lovable with other MCP-connected tools in a single agent session.
## Common use cases
| Scenario | Example prompt to your agent | Outcome |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| Scaffold a new app | *Create a Lovable project called 'Feedback Hub' with a form for collecting user feedback* | Project created and first build completed |
| Iterate on an existing project | *Add a dark mode toggle to my project \[ID]* | Agent sends message and waits for Lovable to finish |
| Review recent changes | *Show me what changed in the last three edits to my project* | Unified diff of recent commits |
| Deploy an app | *Deploy my project \[ID] and give me the live URL* | Project published; live URL returned |
| Inspect the codebase | *List all files in my project and read the main App.tsx* | File tree and file content returned |
| Compare multiple variants | *Build 3 versions of a landing page for \[product], each with a different layout and visual style. Deploy all three and give me the live URLs.* | Three deployed projects with live URLs to compare |
## Prerequisite
* A Lovable account on a **Pro or Business plan**
## Before you connect
Once you connect a client to the Lovable MCP server, it has the same account access you do. A few things to know before connecting:
* **Scope is your full account, not one project.** Whatever you connect (Cursor, Claude Desktop, an n8n flow) can list, read, and edit every project you have access to in Lovable.
* **Calls run live on your account.** Tool calls use real credits and edit real projects.
* **`deploy_project` deploys the app and returns a live URL.** On Free and Pro plans, anyone with the link can reach the app. On Business and Enterprise plans, website access follows the workspace default. The URL may be restricted to workspace members only if internal publishing is configured.
* **`query_database` runs SQL with your full database permissions.** Read, write, and schema changes.
## How to connect
The Lovable MCP server uses OAuth for authentication. When you connect for the first time, your client will open a browser window to authenticate with your Lovable account.
Add the Lovable MCP server through Claude's connector settings. The same flow works in Claude Desktop (macOS and Windows) and on claude.ai.
In Claude, go to **Settings** → **Connectors**.
Click **Add custom connector**.
Set the name to `Lovable` and the URL to `https://mcp.lovable.dev`.
Click **Add** to save the connector.
Sign in to Lovable when Claude prompts you to authenticate.
The Lovable tools appear in the chat composer's tool menu once authentication is complete.
Most MCP clients have a settings page for adding a server by URL. Open your client's MCP or Connectors settings, choose **Add custom MCP server** (or the equivalent), and enter:
* **Name:** `Lovable`
* **URL:** `https://mcp.lovable.dev`
The client will prompt you to authenticate via OAuth in your browser.
Cursor and some other clients may need the **Config file** tab instead, either because they require a `CLIENT_ID` parameter or because their current version doesn't expose OAuth setup in the UI.
Run the following command in your terminal:
```bash theme={null}
claude mcp add --transport http lovable "https://mcp.lovable.dev"
```
Codex support coming soon.
If your client doesn't have a UI for adding MCP servers, or you prefer editing config directly, pick your client below.
Add the following to your MCP configuration:
* **Claude Desktop (macOS):** \
`~/Library/Application Support/Claude/claude_desktop_config.json`
* **Claude Desktop (Windows):**\
`%APPDATA%\Claude\claude_desktop_config.json`
```json theme={null}
{
"mcpServers": {
"lovable": {
"type": "http",
"url": "https://mcp.lovable.dev"
}
}
}
```
If your config file already has an `mcpServers` object with other servers in it, add the `"lovable"` entry **inside** the existing object. Don't paste a second `mcpServers` block, the file won't be valid JSON.
Restart Claude Desktop after saving. The Lovable tools will appear in your agent's tool list.
Add the following to your MCP configuration (`~/.cursor/mcp.json` globally, or `.cursor/mcp.json` in your project root):
```json theme={null}
{
"mcpServers": {
"lovable": {
"type": "http",
"url": "https://mcp.lovable.dev",
"auth": {
"CLIENT_ID": "6d465f583e1e4ce5801b1616f735670c"
}
}
}
}
```
If your `mcp.json` already has an `mcpServers` object with other servers in it, add the `"lovable"` entry **inside** the existing object. Don't paste a second `mcpServers` block, the file won't be valid JSON.
Reload your Cursor window after saving.
Any MCP-compatible agent or AI tool can connect using the [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) at `https://mcp.lovable.dev`.
Consult your client's documentation for how to add an MCP server by URL.
## Available tools
The Lovable MCP server exposes the following tools. All tool calls are workspace-scoped to the OAuth token used.
### Projects and workspaces
| Tool | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_me` | Get the authenticated user's profile and workspaces |
| `list_workspaces` | List all workspaces the user belongs to |
| `get_workspace` | Get details for a specific workspace |
| `list_projects` | Search and list projects in a workspace, with filtering and full-text search |
| `get_project` | Get project details, including editor URL, preview URL, and a screenshot |
| `create_project` | Create a new project, optionally with an initial message to the agent |
| `deploy_project` | Publish a project and get the live URL |
| `remix_project` | Make a copy of an existing project into a workspace. The source project must be accessible to your workspace (your own workspace projects, templates, library projects, or projects with public remixing enabled). |
| `set_project_visibility` | Set who can access the **project in the editor**: `private` (Workspace, all workspace members, default) or `draft` (Restricted, creator only, requires Business or Enterprise). Controls editor access only, not who can visit the published app. |
| `set_folder_visibility` | Set a folder to personal or workspace visibility |
| `list_template_projects` | List available project templates |
| `list_library_projects` | List design system library projects available in a workspace |
### Agent interaction
| Tool | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send_message` | Send a chat message to a project's AI agent and wait for the response. Supports `plan_mode` (discuss before building) and `files` attachments. Pass `wait=false` to return immediately and poll with `get_message` instead. |
| `get_message` | Poll for message completion status after `send_message` with `wait=false` |
### Code inspection
| Tool | Description |
| ------------ | -------------------------------------------------------- |
| `get_diff` | Get the unified diff from a message or commit SHA |
| `list_files` | List all files in a project at a specific git ref |
| `read_file` | Read the contents of a single file at a specific git ref |
| `list_edits` | List the edit history of a project with pagination |
### Knowledge
| Tool | Description |
| ------------------------- | ------------------------------------------ |
| `get_workspace_knowledge` | Get the workspace's custom AI instructions |
| `set_workspace_knowledge` | Set the workspace's custom AI instructions |
| `get_project_knowledge` | Get a project's custom AI instructions |
| `set_project_knowledge` | Set a project's custom AI instructions |
### Cloud database
| Tool | Description |
| ------------------------------ | ----------------------------------------------------------------- |
| `get_database_status` | Check whether Lovable Cloud is enabled for a project |
| `enable_database` | Enable Lovable Cloud on a Lovable project (takes 30-60 seconds) |
| `query_database` | Execute an SQL query on a Lovable Cloud project |
| `get_database_connection_info` | Get the connection string and API URL for a Lovable Cloud project |
### Connected MCP servers
| Tool | Description |
| ------------------- | ------------------------------------------------------------------- |
| `list_mcp_servers` | List all MCP servers connected to a workspace |
| `list_mcp_catalog` | Browse featured MCP server templates available to add |
| `list_connectors` | List available connector integrations (standard, seamless, and MCP) |
| `list_connections` | List authenticated connector accounts for a workspace |
| `add_mcp_server` | Add an MCP server (catalog or custom) to a workspace |
| `remove_mcp_server` | Remove an MCP server from a workspace |
### Analytics
| Tool | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_project_analytics` | Get historical analytics for a published project: visitors, pageviews, bounce rate, session duration, and breakdowns by page, source, device, and country. Requires `start_date` and `end_date` (RFC 3339). |
| `get_project_analytics_trend` | Get real-time visitor count and 5-minute trend for a published project |
### File uploads
| Tool | Description |
| --------------------- | -------------------------------------------------------------------- |
| `get_file_upload_url` | Get a presigned URL to upload a file for use as a message attachment |
## Skills
A skill is a reusable instruction file that tells your AI client how to use the Lovable MCP server effectively: when to trigger it, how to sequence tool calls, and what patterns to follow. Add it to your client once and it will know how to drive Lovable without extra prompting.
Copy this file and add it to your AI client's skills or instructions directory.
````markdown theme={null}
---
name: lovable-mcp
description: >
Use Lovable's MCP server to create, iterate on, and deploy full-stack web apps from natural-language prompts.
Trigger this skill whenever the user wants to build a web app, dashboard, internal tool, prototype, landing page,
or any frontend/full-stack project using Lovable — whether they say "Lovable" explicitly or just need a working
app built and deployed fast. Also trigger when the user wants to manage Lovable projects programmatically:
listing workspace projects, auditing edit history, reviewing diffs, reading project files, checking deployment
status, managing databases, or setting AI governance policies. If the user mentions "Lovable," "lovable project,"
"lovable app," or asks to build/ship/deploy a web app and Lovable is available as a connected MCP, use this skill.
Even if they just say "make me an app" or "build a dashboard for X" — if the Lovable MCP is connected, this skill
applies. Covers the full lifecycle: create → iterate → review → deploy.
---
# Lovable MCP Server
Build, iterate, inspect, and deploy full-stack web apps through Lovable's MCP server — without ever opening the Lovable UI.
Lovable's agent handles the heavy lifting: you describe what you want in plain language, and it builds a working app (React + Vite + Tailwind + Supabase when needed). The MCP server exposes this capability programmatically, so you can drive the entire workflow from any agent that supports skills.
## When to use this skill
- The user wants a **new web app, dashboard, prototype, or internal tool** built from a description
- The user wants to **iterate** on an existing Lovable project (add features, fix bugs, change design)
- The user needs to **inspect** a Lovable project: read source files, review diffs, trace edit history
- The user wants to **deploy** a Lovable project to production
- The user needs **workspace management**: list projects, audit activity, set governance policies
- The user wants to **provision or query a database** on Lovable Cloud
---
## Core Workflow
The typical flow is: **create → iterate → review → deploy**. Each step maps to specific tools.
### 1. Create a project
Use `create_project` with a clear, detailed prompt. The Lovable agent starts building immediately.
```
create_project(
workspace_id: "your-workspace-id", // required — get from list_workspaces()
description: "Project management dashboard", // required — short project name
initial_message: "Build a project management dashboard with a kanban board,
team member list, and a sidebar for filtering by status and assignee.
Use a clean, modern design with a dark mode toggle."
)
```
Returns: `project_id`, `editor_url`, `preview_url`, `sandbox_url`.
**Full parameter list:**
- `workspace_id` (required) — target workspace
- `description` (required) — short project name, shown in the editor
- `initial_message` (optional) — the build prompt sent to the Lovable agent; omit to create a blank project
- `tech_stack` (optional, default: `vite`) — override if you need a specific stack
- `template_project_id` (optional) — clone from a template; get IDs from `list_template_projects`
- `selected_libraries` (optional) — attach workspace design system libraries; get IDs from `list_library_projects`
- `visibility` (optional) — `draft` (Restricted: creator only, requires Business or Enterprise) or `private` (Workspace: all workspace members, default)
**Prompting tips for initial_message:**
- Be specific about what the app should do, not just what it should look like. Lovable's agent is strongest when it understands the *purpose*.
- Mention the data model if you have one in mind ("each task has a title, status, assignee, and due date").
- If you want a particular tech choice, say so — otherwise Lovable picks sensible defaults (React, Vite, Tailwind, shadcn/ui).
- You can reference design inspirations: "similar layout to Linear" or "card-based like Trello."
### 2. Iterate on what's built
Use `send_message` to talk to the Lovable agent on an existing project. This is the same agent quality as the Lovable UI — treat it like a conversation with a skilled developer who can see the entire codebase.
```
send_message(project_id: "...", message: "Add a drag-and-drop feature to the kanban columns.
Also, the header font feels too heavy — switch to Inter at 500 weight.")
```
Returns: `message_id`. Use this with `get_diff` to see exactly what changed.
**Iteration best practices:**
- One conceptual change per message tends to produce cleaner results than cramming five unrelated requests together.
- If something went wrong, describe *what you see* and *what you expected* — the agent debugs well when given concrete symptoms.
- You can reference specific files: "In `src/components/KanbanBoard.tsx`, the drag handler doesn't update state correctly."
### 3. Review changes
Use `get_diff` with the `message_id` from `send_message` to inspect what the agent changed. This is your code review step.
```
get_diff(project_id: "...", message_id: "...")
```
If you want broader context:
- `list_files` → discover the project structure at any commit
- `read_file` → read the full contents of any file (requires a git ref — get `latest_commit_sha` from `get_project`)
- `list_edits` → see the full edit history with timestamps, prompts, and commit SHAs
### 4. Deploy
Use `deploy_project` to publish the current build to production.
```
deploy_project(project_id: "...")
```
Returns: the live production URL. On Free and Pro plans the app is publicly accessible immediately. On Business and Enterprise plans, access follows the project or workspace website access setting.
---
## Tool Reference
### Project Operations
| Tool | What it does | When to use it |
|---|---|---|
| `create_project` | Creates a new Lovable project from a prompt | Starting a new app, dashboard, tool, or prototype |
| `send_message` | Sends a prompt to the Lovable agent on an existing project | Iterating — adding features, fixing bugs, changing design |
| `get_project` | Returns project details (URLs, latest commit, publish status) | Before any project operation, to confirm state and get current refs |
| `list_projects` | Lists all workspace projects (supports search) | Discovery, auditing, finding a project by name |
| `deploy_project` | Publishes current build to production | Shipping the app |
### Code & History Inspection
| Tool | What it does | When to use it |
|---|---|---|
| `list_files` | Lists all files at a git ref | Discovering project structure before reading specific files |
| `read_file` | Returns full file contents at a git ref | Inspecting source code, config, or any project artifact |
| `get_diff` | Returns the diff for a specific edit (by message_id) | Reviewing what changed after a `send_message` |
| `list_edits` | Full edit history (reverse chronological) | Understanding how a project evolved, locating past changes |
| `get_message` | Status and details of a specific message/edit | Checking if a `send_message` completed, is running, or failed |
### Workspace Governance
| Tool | What it does | When to use it |
|---|---|---|
| `list_workspaces` | Lists all workspaces the user belongs to | First call if workspace_id is unknown — most tools require it |
| `get_workspace` | Workspace details: plan, credits, members, settings | Checking account state and available credits |
| `get_workspace_knowledge` | Returns AI governance policies for the workspace | Understanding what rules apply across all projects |
| `set_workspace_knowledge` | Sets AI governance policies workspace-wide | Defining standards (stack constraints, naming, security rules) |
| `get_project_knowledge` | Returns project-specific AI context | Understanding a project's defined stack and constraints |
| `set_project_knowledge` | Sets project-specific AI context | Defining tech stack, architecture decisions, or constraints for a project |
### Database (Lovable Cloud)
| Tool | What it does | When to use it |
|---|---|---|
| `get_database_status` | Checks if Lovable Cloud DB is enabled | Before any database operation |
| `enable_database` | Provisions a PostgreSQL database for the project | When the project needs persistent data storage (one-time) |
| `query_database` | Runs SQL against the project's database | Inspecting data, debugging schema, verifying migrations |
| `get_database_connection_info` | Returns credentials and connection strings | Connecting external tools (psql, pgAdmin, ORMs) to the DB |
### Analytics
| Tool | What it does | When to use it |
|---|---|---|
| `get_project_analytics` | Historical visitor metrics (pageviews, bounce rate, etc.) | Assessing how a deployed app is performing |
| `get_project_analytics_trend` | Real-time visitor count + 5-min intervals | Monitoring traffic right after a deploy |
### File Uploads
| Tool | What it does | When to use it |
|---|---|---|
| `get_file_upload_url` | Returns a signed URL for uploading a file to a project | Adding assets, data files, or binary content |
### MCP Management
| Tool | What it does | When to use it |
|---|---|---|
| `list_mcp_catalog` | Lists available MCP servers in the Lovable catalog | Discovering what external tools can be connected |
| `list_mcp_servers` | Lists MCP servers connected to a project | Checking what tools the agent currently has access to |
| `add_mcp_server` | Connects an MCP server to a project | Extending agent capabilities with external services |
| `remove_mcp_server` | Disconnects an MCP server from a project | Revoking agent access to a tool |
### Templates & Library
| Tool | What it does | When to use it |
|---|---|---|
| `list_library_projects` | Lists projects saved to the workspace library | Finding reusable templates your team has built |
| `list_template_projects` | Lists official Lovable starter templates | Finding a starting point before `create_project` |
### Authentication
| Tool | What it does | When to use it |
|---|---|---|
| `get_me` | Returns authenticated user details | Confirming auth works and retrieving user ID |
---
## Common Patterns
### Build and deploy in one flow
```
1. list_workspaces() → get workspace_id
2. create_project(workspace_id, description, → get project_id
initial_message: "...")
3. get_project(project_id) → confirm it's built, get preview_url
4. send_message(project_id, "...") → iterate if needed
5. get_diff(project_id, message_id) → review changes
6. deploy_project(project_id) → ship it
```
### Audit a workspace
```
1. list_workspaces() → get workspace_id
2. list_projects(workspace_id) → see all projects
3. For each project of interest:
- list_edits(project_id) → review edit history
- read_file(project_id, ref, path) → inspect code
- get_database_status(project_id) → check DB state
```
### Debug a stuck project
When a user has a Lovable project that isn't working right:
```
1. get_project(project_id) → get latest commit SHA
2. list_files(project_id, ref) → understand the structure
3. read_file(project_id, ref, path) → read the relevant files
4. list_edits(project_id) → understand what changed recently
5. get_diff(project_id, message_id) → inspect the last few edits
6. send_message(project_id, "...") → send a targeted fix based on what you found
```
### Set governance before a build
For teams that want consistent standards across projects:
```
1. list_workspaces() → get workspace_id
2. set_workspace_knowledge(workspace_id, "Always use TypeScript strict mode.
All components must use shadcn/ui. No inline styles. Use Zustand for state management.")
3. create_project(workspace_id, description, initial_message: "...") → new project inherits these rules
```
---
## Important Notes
- **`create_project` requires both `workspace_id` and `description`.** Call `list_workspaces` first if you don't have a workspace_id. The build prompt goes in `initial_message`, not `prompt`.
- **Always call `list_workspaces` first** if you don't already have a `workspace_id`. Most tools require it.
- **`read_file` needs a git ref.** Get `latest_commit_sha` from `get_project` before reading files.
- **`get_diff` uses `message_id`**, not commit SHA. Save the message_id from `send_message`.
- **`send_message` may take time.** The Lovable agent is building real code. Use `get_message` to poll status if needed.
- **One database per project.** `enable_database` is a one-time operation. It provisions PostgreSQL via Lovable Cloud.
- **Deployed app access follows your plan's website access settings.** On Free and Pro plans, anyone with the URL can visit the app. On Business and Enterprise plans, the URL may be restricted to workspace members if internal publishing is configured.
- **Credit usage.** Every `create_project` and `send_message` draws from the workspace's build credit pool. Check `get_workspace` if you're unsure about remaining credits.
- **Research Preview.** The MCP server is available to paid Lovable users only.
````
## FAQ
[Chat connectors](/integrations/mcp-servers) let the **Lovable agent** connect to your external tools (for example, Notion, Linear, Miro) during a build session. The Lovable MCP server is the reverse: it lets **your external agent** (Claude Desktop, Cursor, a custom script) connect to Lovable and control it programmatically.
API key authentication is not currently available. OAuth is the only supported way to connect to the Lovable MCP server.
Standard Lovable credits apply to `create_project` and `send_message` calls. Other tools are free.
The MCP server inherits your Lovable user permissions exactly, with no additional surface area.
The Lovable MCP server is new infrastructure. Tool names, parameters, and response shapes may change as we refine the MCP server based on real-world usage.
## Troubleshooting
Run `tools/list` to confirm the connection. If tools don't appear, troubleshoot based on how you connected:
* **Connected through the client's UI (OAuth):** Open your client's connector/MCP settings, remove the Lovable entry, and add it again to re-run the OAuth flow.
* **Using a config file:** Open the config file and confirm the JSON is valid and the `"lovable"` entry is nested inside the existing `mcpServers` object. Restart the client after saving.
Call `list_workspaces` to retrieve valid workspace IDs. The personal workspace is used by default if `workspace_id` is omitted.
The project ID is incorrect or the project was deleted. Call `list_projects` with the workspace ID to find the correct ID.
The project doesn't have a database provisioned. Call `enable_database` first (takes 30–60 seconds), then retry.
Confirm the table exists using `list_files` to browse the project schema, or run a `SELECT table_name FROM information_schema.tables` query first.