frappe-connector
A lightweight Python client for connecting and interacting with Frappe instances.
Installation
pip install frappe-connector # library + CLI
pip install "frappe-connector[mcp]" # also the MCP server
The package ships three ways to use it:
- a Python library (
FrappeConnector, below) - a command-line tool,
fcn(see CLI) - an MCP server,
frappe-connector-mcp, that gives AI assistants access to your site (see MCP server)
Authentication
Session login (username + password)
from frappe_connector import FrappeConnector
client = FrappeConnector(
"https://erp.example.com",
username="admin",
password="secret",
)
Token login (API key + secret)
client = FrappeConnector(
"https://erp.example.com",
api_key="your_api_key",
api_secret="your_api_secret",
)
Connection options
client = FrappeConnector(
"https://erp.example.com",
api_key="...",
api_secret="...",
ssl_verify=False, # skip TLS certificate checks (self-signed certs)
timeout=60, # seconds per request (default 30)
)
Context manager (auto-logout)
with FrappeConnector("https://erp.example.com", username="admin", password="secret") as client:
records = client.get_list("Customer")
CRUD Operations
get_list — fetch multiple records
customers = client.get_list(
"Customer",
fields=["name", "customer_name", "email_id"],
filters={"status": "Active"},
offset=0,
page_size=20, # omit for the server default (20), 0 for all records
order_by="creation desc",
)
get_doc — fetch a single document
# by name
customer = client.get_doc("Customer", name="CUST-00001")
# by filter: returns the first matching document
customer = client.get_doc(
"Customer",
filters={"customer_name": "Acme Corp"},
fields=["name", "customer_name", "email_id"],
)
create_doc — insert a new document
new_customer = client.create_doc({
"doctype": "Customer",
"customer_name": "Globex Corporation",
"customer_type": "Company",
"customer_group": "Commercial",
"territory": "All Territories",
})
update_doc — update an existing document
updated = client.update_doc({
"doctype": "Customer",
"name": "CUST-00001",
"phone": "+977-9800000000",
})
delete_doc — delete a document
client.delete_doc("Customer", "CUST-99999")
rename_doc — rename a document
client.rename_doc("Customer", old_name="CUST-OLD", new_name="CUST-NEW")
submit_doc — submit a document
client.submit_doc({"doctype": "Sales Invoice", "name": "SINV-00001"})
# or several at once (returns a list of results)
client.submit_doc([
{"doctype": "Sales Invoice", "name": "SINV-00001"},
{"doctype": "Sales Invoice", "name": "SINV-00002"},
])
API Method Calls
get_api — call a whitelisted GET method
result = client.get_api("myapp.api.get_summary", params={"year": 2025})
post_api — call a whitelisted POST method
result = client.post_api("myapp.api.process_order", params={"order_id": "ORD-001"})
Error Handling
All exceptions inherit from FrappeException, so you can catch broadly or specifically.
from frappe_connector import FrappeConnector, LoginFailedError, ServerError, FrappeException
try:
client = FrappeConnector("https://erp.example.com", username="admin", password="wrong")
except LoginFailedError as e:
print(e) # "Invalid credentials or login rejected by server."
try:
client.get_doc("Customer", "CUST-001")
except ServerError as e:
print(e.exc_type) # e.g. "DoesNotExistError"
print(e.server_traceback) # full traceback from Frappe
print(e.response) # raw requests.Response object
except FrappeException as e:
print(e)
| Exception | When raised |
|---|---|
FrappeException |
Base class for all library errors |
LoginFailedError |
Credentials rejected by the server |
ServerError |
Server returned an exception in the response body |
Other HTTP errors (e.g. 403 permission denied) and non-JSON responses raise
FrappeException with the server's message. Network failures raise the usual
requests exceptions.
Closing the session
client.close() # logs out (session login) and closes the HTTP connection
Configuration via environment variables
The CLI and MCP server read their connection settings from these variables
(the CLI also accepts matching --url, --api-key, … flags):
| Variable | Meaning |
|---|---|
FRAPPE_URL |
Base URL of the site (required) |
FRAPPE_API_KEY |
API key (token auth) |
FRAPPE_API_SECRET |
API secret (token auth) |
FRAPPE_USERNAME |
Username (session auth) |
FRAPPE_PASSWORD |
Password (session auth) |
FRAPPE_SSL_VERIFY |
0 / false to skip TLS certificate checks |
FRAPPE_TIMEOUT |
Request timeout in seconds (default 30) |
CLI
export FRAPPE_URL=https://erp.example.com
export FRAPPE_API_KEY=your_api_key FRAPPE_API_SECRET=your_api_secret
fcn list Customer --fields name,customer_name --filters '{"disabled": 0}' --limit 50
fcn get Customer CUST-00001
fcn get Customer --filters '{"customer_name": "Acme Corp"}' --fields name,email_id
fcn create Customer '{"customer_name": "Globex", "customer_group": "Commercial"}'
fcn update Customer CUST-00001 @changes.json # JSON from a file
cat doc.json | fcn create Customer - # JSON from stdin
fcn rename Customer CUST-OLD CUST-NEW
fcn submit "Sales Invoice" SINV-00001 --yes
fcn delete Customer CUST-99999 --yes
fcn call frappe.client.get_count --get --params '{"doctype": "Customer"}'
Results are printed as JSON (--compact for one line), so they pipe nicely
into jq. delete and submit ask for confirmation unless --yes is given.
Errors go to stderr with exit code 1. Run fcn COMMAND --help for all options.
frappe-connector is a longer alias for fcn, and python -m frappe_connector
works too.
MCP server
frappe-connector-mcp is a Model Context Protocol
server that lets AI assistants (Claude Desktop, Claude Code, …) work with your
Frappe site. Install the extra first: pip install "frappe-connector[mcp]".
Tools:
| Tool | Does |
|---|---|
list_documents |
List documents with fields, filters, sorting, paging |
get_document |
Fetch one document by name or filters |
create_document |
Create a document |
update_document |
Update fields on a document |
delete_document |
Delete a document |
rename_document |
Rename a document |
submit_document |
Submit a draft document |
call_method |
Call a whitelisted server method |
Start it with --read-only (or FRAPPE_MCP_READ_ONLY=1) to expose only
list_documents and get_document.
Claude Code:
claude mcp add frappe \
-e FRAPPE_URL=https://erp.example.com \
-e FRAPPE_API_KEY=your_api_key \
-e FRAPPE_API_SECRET=your_api_secret \
-- frappe-connector-mcp --read-only
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"frappe": {
"command": "uvx",
"args": ["--from", "frappe-connector[mcp]", "frappe-connector-mcp"],
"env": {
"FRAPPE_URL": "https://erp.example.com",
"FRAPPE_API_KEY": "your_api_key",
"FRAPPE_API_SECRET": "your_api_secret"
}
}
}
}
The server uses stdio by default; --transport streamable-http --host 127.0.0.1 --port 8000
serves it over HTTP instead. The tools act with the permissions of the
configured Frappe user, so a dedicated user with limited roles is a good idea.
Development
uv sync --all-extras
uv run pytest
Releasing
- Bump
versioninpyproject.tomland merge tomain. - Tag and push:
git tag v0.2.0 && git push origin v0.2.0.
The publish workflow runs the tests on Python 3.10–3.13, checks that the tag matches the package version, builds, and uploads to PyPI via trusted publishing.
Metadata
Release files for frappe-connector 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| frappe_connector-0.2.0.tar.gz | 96.5 kB | With provenance | Details for frappe_connector-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| frappe_connector-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for frappe_connector-0.2.0-py3-none-any.whl |
Total release size: 112.6 kB
Release files / frappe_connector-0.2.0.tar.gz
| Download URL | frappe_connector-0.2.0.tar.gz |
|---|---|
| Size | 96.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9abd58f6f12a35e47ce3667535a19695d32dcbae0d06bcbaf6fa992a7354dc27
|
|
BLAKE2b-256 checksum How to use checksums |
d33555c3bf1fdfc82a76a28b38cd25f2bf6f1ff9803d232a4f5242907908f366
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / frappe_connector-0.2.0-py3-none-any.whl
| Download URL | frappe_connector-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0d0894ae42f224ed4c409ab7080085884f988567a393edd1c6f8b6a15ec77fb6
|
|
BLAKE2b-256 checksum How to use checksums |
3f8fbd0d1a632f80723fe6d75590184a972f4f41c992e4260d99b98d0eae4e9b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logSecurity for frappe-connector 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for frappe_connector-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.