Connecting Agents using MCP or CLI
Frappe gives two ways to connect an LLM or an AI agent to a Frappe site:
- MCP server. Frappe has a built-in Model Context Protocol (MCP) server. Use it with MCP clients, for example Claude Desktop, Claude Code and Codex.
- frappectl CLI.
frappectlis a command-line client for the Frappe REST API v2. Use it with coding agents that can run shell commands, for example Claude Code, Codex, pi and opencode.
Both use the permissions of the user who logs in.
Note: The MCP server and
frappectlrequire Frappe v16 or later.
Select a method
| Use | When |
|---|---|
| MCP server | The agent cannot run shell commands, for example Claude Desktop. You do not want to install software on the computer. |
| frappectl CLI | The agent has a terminal. The agent must send output to jq or to files, run scripts or use many sites with one tool. |
MCP server
Frappe includes a built-in Model Context Protocol (MCP) server. MCP clients can use its tools to find DocTypes and methods, read and change documents, and call whitelisted methods on a Frappe site.
The server uses Streamable HTTP at /api/v2/mcp. For a site at https://erp.example.com, the endpoint is:
https://erp.example.com/api/v2/mcp
MCP tools provide a client interface to Frappe. They are not REST API endpoints. Document tools use Frappe’s REST API v2 handlers and permission checks.
Enable MCP
MCP is enabled by default on new sites. To check or change the setting:
-
Sign in to the Desk as a System Manager.
-
Open System Settings.
-
Select the AI Agents tab.
-
Select Enable MCP to enable the endpoint, or clear it to disable the endpoint.
-
Save the settings.
Set up OAuth
Configure OAuth on the Frappe site before connecting a client. See How to set up OAuth 2.
If a client uses dynamic client registration, enable Enable Dynamic Client Registration in OAuth Settings. During connection, the client opens a browser for Frappe sign-in and authorization, then returns to the client.
Connect an MCP client
Use your site’s MCP endpoint:
https://erp.example.com/api/v2/mcp
Claude
In Claude Desktop:
-
Open Settings > Connectors.
-
Select Add custom connector.
-
Enter a name, such as
Frappe, and the endpoint URL.
-
Select Add, then connect and authorize the server.

For Team and Enterprise plans, open Organization connectors before adding the connector.
In Claude Code:
claude mcp add --transport http frappe \
https://erp.example.com/api/v2/mcp
claude mcp login frappe
See Anthropic’s guides for remote MCP connectors and Claude Code MCP.
Codex
In the Codex desktop app:
-
Open Settings > Plugins.
-
Select Add MCP server.
-
Enter a name, choose Streamable HTTP, and enter the endpoint URL.

-
Save the server, then select Authenticate.

In Codex CLI:
codex mcp add frappe \
--url https://erp.example.com/api/v2/mcp
codex mcp login frappe
Run codex mcp list to check the connection. The Codex desktop app and CLI share their MCP configuration. See the Codex MCP guide.
Use an API token
Use an API token if OAuth is not available for your client. As a System Manager, open the Frappe user’s User document, open API Access, and select Generate Keys.
Configure the client to send this header:
Authorization: token API_KEY:API_SECRET
The server applies the permissions of the user that owns the keys. Store the API secret in a password manager or the client’s secret store. See Token Based Authentication.
Available tools
The Frappe MCP server exposes 13 tools. The MCP client retrieves each tool’s description and input schema when it connects.
| Tool | Purpose |
|---|---|
search_doctypes |
Find DocTypes by name. |
get_doctype_schema |
Get a DocType’s fields and the current user’s permissions. |
search_methods |
Find whitelisted methods and document methods. |
get_method_schema |
Get a method’s arguments and documentation. |
list_document_methods |
List whitelisted methods for a DocType. |
list_documents |
List documents that match filters. |
get_document |
Read a document and its permitted child rows. |
count_documents |
Count documents that match filters. |
create_document |
Create a document. |
update_document |
Update a document. |
delete_document |
Delete a document. |
call_method |
Call a whitelisted method by its dotted path or an API Server Script. |
call_document_method |
Call a whitelisted method on a document, such as submit or cancel. |
list_documents returns up to 20 documents by default. Check has_next_page in the result to see if another page is available. Increase start to request the next page.
Document filters, fields, and ordering follow REST API v2 behavior. See REST API and Manipulating DocTypes.
Permissions and method behavior
The server requires an authenticated Desk user. DocType and method discovery return metadata. They do not grant access to documents or methods.
Document tools use Frappe’s permission checks. Users need read permission to list or read documents, create permission to create documents, write permission to update documents, and delete permission to delete documents. Frappe also checks field-level permissions and document-specific rules.
Method tools can call only whitelisted methods. Frappe applies each method’s existing HTTP method and permission checks. A method whitelisted for GET but not POST runs as GET. This requires read permission, and Frappe rolls back database writes made by that method. Other methods run as POST.
See Users and Permissions for details.
Configure site instructions
Open System Settings > AI Agents to configure the MCP server:
-
Server Name sets the name the server advertises to clients. It does not set the name you choose when adding the server in a client. If empty, Frappe derives the name from the site host. For example,
erp.example.combecomeserp_example_com. -
Agent Instructions adds site-specific guidance to the instructions Frappe sends to clients. Use it to explain the site’s purpose, workflows, or terms your team uses.
For example:
This site tracks customer support requests in the Issue DocType. Before creating a request, check for an open Issue from the same customer about the same problem.Agent Instructions guide the client. They do not grant permissions or access to data.

Troubleshooting
| Response | Check |
|---|---|
401 |
Check the credentials and Authorization header. |
403 |
Check that the user has Desk access and that the request origin is allowed by the site’s CORS settings. |
404 |
Check the endpoint URL and the Enable MCP setting. |
405 |
Send requests through POST. Opening the endpoint URL in a browser sends GET. |
406 |
Make sure the client accepts application/json. |
415 |
Make sure the client sends Content-Type: application/json. |
frappectl CLI
frappectl is a command-line client for the Frappe REST API v2. It works with Frappe v16 and later. Humans and AI coding agents can use it. Examples of coding agents are Claude Code, Codex, pi and opencode.
A coding agent that can run shell commands can use frappectl to read and change data on a Frappe site. The agent gets the same permissions as the user who logs in.
Overview
- One guide for the agent. The
frappectl guidecommand shows a short guide on one screen. The guide tells how to select a site, how to use the core commands, how to filter and how to call the raw API. The agent reads this guide before it starts work. - Clean output. When you pipe the output or use
--json,frappectlwrites clean JSON to stdout. Logs and errors go to stderr. - Safe default. A new profile is read-only. It stops all write requests before they leave your computer.
- No secrets in prompts. Credentials stay in the OS keyring or in environment variables. The agent does not see them.
Install frappectl
Install frappectl with uv or pip:
uv tool install frappectl
# or: pip install frappectl
# development version: uv tool install git+https://github.com/frappe/frappectl
This installs two commands: frappectl and its short alias fr.
To upgrade frappectl, run frappectl update.
Log in to a site
frappectl has three authentication methods. For agents, use OAuth.
OAuth
OAuth stores no secret. The access tokens have a short life, and frappectl refreshes them automatically.
To log in with OAuth:
-
Run the login command:
frappectl auth login https://erp.example.com --oauth -
Sign in to the site in the browser window that opens.
-
Allow access.
If the site has dynamic client registration, frappectl creates the OAuth client automatically. Frappe v15 and later have this feature by default. For other sites, register a public OAuth client first. Then give its ID with --client-id:
frappectl auth login https://erp.example.com --oauth --client-id <public-client-id>
For more information, see How to set up OAuth 2.
OAuth needs a terminal and a local browser. Thus a human must run the login command. You cannot use OAuth on a computer without a display.
API key and secret
To log in with an API key:
-
In the Desk, open User > Settings > API Access.
-
Generate an API key and an API secret.
-
Run the login command:
frappectl auth login https://erp.example.com -
Enter the API key and the API secret when the command asks for them.
frappectl stores the site URL in ~/.config/frappe/config.json. It stores the secret in the OS keyring. It does not store secrets as plain text. If your computer has no keyring, use environment variables.
Environment variables
Environment variables always have priority over stored profiles. They do not use the keyring. Use them on servers without a display and in CI.
export FRAPPE_SITE=https://erp.example.com
export FRAPPE_API_KEY=xxxxxxxx
export FRAPPE_API_SECRET=yyyyyyyy
Manage sites
Each login makes a profile. Give each profile a name and a description. The agent reads the description to select the correct site.
frappectl auth login https://erp.example.com --oauth --name erp --description "Production ERPNext"
frappectl auth login https://dev.example.com --oauth --name dev --writable --default
frappectl auth list # show all stored profiles
frappectl auth default erp # change the default profile
frappectl auth whoami -s erp # show the site and the user
frappectl auth logout erp # remove a profile
To select a profile for one command, use -s <profile> or --site <profile>:
frappectl -s erp doc list "Sales Invoice" --json
Read-only profiles
A new profile is read-only by default. A read-only profile stops all unsafe HTTP methods before the request leaves your computer. Thus a test command from an agent cannot change the site by accident.
frappectl auth login https://prod.example.com --oauth --name prod # read-only
frappectl auth login https://dev.example.com --oauth --name dev --writable # allows writes
frappectl auth configure prod --read-only # lock a profile
frappectl auth configure prod --writable # allow writes again
A read-only profile stops these commands:
doc create,doc update,doc deleteanddoc submitfile upload- method calls through
apiandmethod
Read commands continue to work. Examples are doc list, doc get, doctype show and report run.
If you use environment variables, set FRAPPE_READ_ONLY=1 to make the session read-only.
To call a whitelisted read method with a read-only profile, use the GET method:
frappectl api method/<path> -X GET
Tip: Keep production profiles read-only. Make a profile writable only for sites where an agent can make changes.
Connect a coding agent
Use frappectl assistant
The frappectl assistant command starts a supported coding agent with a Frappe system prompt. The agent then uses frappectl on your sites.
frappectl assistant # start the first supported agent that is installed
frappectl assistant claude # Claude Code
frappectl assistant codex # Codex CLI
frappectl assistant pi
frappectl assistant opencode
frappectl assistant flow # open a web UI in the browser
To send a prompt to the agent, put it after --:
frappectl assistant pi -- "list overdue invoices on staging"
To see the environment, the files and the command without starting the agent, use --dry-run.
Use a different agent
Each agent that can run shell commands can use frappectl.
To connect a different agent:
-
Install
frappectland log in to your sites. -
Open the instructions file of the agent, for example
AGENTS.mdorCLAUDE.md. -
Add these instructions:
Use `frappectl` to inspect or operate on Frappe sites. Run `frappectl guide` before you start, and `frappectl auth list` to see the available sites. Pass `-s <profile>` when the task names a site.
The frappectl guide command needs no site and no login. Its output includes the list of profiles. Thus the agent knows which sites it can use.
frappectl does not ask for confirmation before a change. The agent harness or you must confirm each change. Use read-only profiles for important sites.
Commands
| Command | Description |
|---|---|
frappectl doc list <DocType> |
List documents. Use -f, --fields, --limit and --all. |
frappectl doc get <DocType> <name> |
Get one document. |
frappectl doc create <DocType> |
Create a document from --set values, from piped JSON or from --input JSON. |
frappectl doc update <DocType> <name> |
Update a document. The command fails if a different user changed the document. Use --force to overwrite. |
frappectl doc delete <DocType> <name> |
Delete a document. |
frappectl doc submit\|cancel\|amend |
Submit, cancel or amend a document. |
frappectl doctype list / frappectl doctype show <name> |
List DocTypes and show their schema. |
frappectl report run <name> |
Run a report. Use the same filters as doc list. |
frappectl query <sql> |
Run read-only SQL through the System Console. You must have the System Manager role or be Administrator. |
frappectl method search\|list\|show |
Find whitelisted methods. These include RPC paths and DocType methods. |
frappectl method call <path> |
Call an RPC method. To call a DocType method, add --doctype and --name. |
frappectl file upload\|download |
Upload or download files. Upload accepts --doctype, --name and --private. |
frappectl api <path> |
Call a raw v2 API, for example frappectl api method/<path> -F key=value. |
frappectl guide |
Show the agent guide. This command needs no site and no login. |
frappectl assistant [tool] |
Start a coding agent with a Frappe system prompt. |
frappectl update |
Upgrade frappectl with uv tool upgrade. |
Examples
frappectl doctype show "Sales Invoice" --json # get the schema first
frappectl doc list "Sales Invoice" -f status=Overdue -f 'grand_total>1000' \
--fields name,customer,grand_total --all --json
frappectl doc get "Sales Invoice" SINV-0001
frappectl doc create ToDo --set description="Follow up" --set priority=High
cat invoice.json | frappectl doc create "Sales Invoice" # use JSON for child tables
frappectl doc submit "Sales Invoice" SINV-0001
frappectl doc delete ToDo abc123
frappectl report run "Accounts Receivable" -f company="Frappe" --json
frappectl query 'select count(*) as users from tabUser'
frappectl file upload ./contract.pdf --doctype "Sales Invoice" --name SINV-0001 --private
frappectl api method/frappe.client.get_count -F doctype=User
Filters
For simple filters, use -f. To combine filters, use -f more than one time. You can use these operators: =, >, <, >=, <= and like.
frappectl doc list ToDo -f status=Open -f priority=High
frappectl doc list "Sales Invoice" -f 'grand_total>1000' -f 'customer like %Inc%'
For in, between, child table filters and other filters, use the Frappe filter JSON:
frappectl doc list "Sales Invoice" --filters-json '[["status","in",["Paid","Overdue"]]]'
Output and scripts
- Terminal:
frappectlshows tables with colors. - Pipe or
--json:frappectlwrites clean JSON to stdout. Logs and errors go to stderr. Thus you can safely send the output tojq. - Changes:
frappectldoes not ask for confirmation. The caller must confirm. The caller is you or the agent harness. - Exit codes:
0is success,1is failure and2is a usage error. --debug:frappectlwrites the method, the URL and the headers to stderr. It hides credentials. For some endpoints, such asdoc list, it also writes the server SQL. It does not write to stdout, so the--jsonoutput stays correct.
frappectl shows server error messages as plain text. It removes HTML from them.