Skip to main content

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

  1. Bump version in pyproject.toml and merge to main.
  2. 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)

Source distribution for frappe-connector 0.2.0
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)

Table of built distributions (wheels) for frappe-connector 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page