frappe

This MCP server implements a Python-based Frappe integration exposed via the MCP (Model Context Protocol). It enables you to perform typical Frappe operations through a standardized set of MCP tools. You can manage documents (create, read, update, delete, list), introspect DocTypes (schemas and field options), generate reports, and call whitelisted Frappe methods. The server uses uv for dependency management and is packaged to run in Docker, providing a self-contained environment that connects to your Frappe site using API credentials defined in the environment.

To use, start the server via the provided Docker setup and then interact with the available MCP tools. For example, you can create a new document with create_document, fetch a document with get_document, or run a query-based report with run_query_report. Authentication relies on your API key/secret configured in the environment, and you can validate credentials using validate_auth. Use get_doctype_schema and get_doctype_list to explore your Frappe DocTypes and their fields, and rely on get_field_options for Link/Select field choices. The tools are divided into Document, Schema, Report, and Helper operations for easy navigation and automation.

Prerequisites: Docker, Docker Compose, and access to a Frappe site with API credentials.

1. Clone the MCP server repository:

   • git clone https://github.com/appliedrelevance/frappe_mcp_server_uv.git
   • cd frappe_mcp_server_uv

2. Copy and configure environment:

   • cp .env.example .env
   • Edit .env to include your Frappe site URL and API credentials (API key/secret) as required by the server.

3. Start the MCP server using Docker Compose (as demonstrated in the Quick Start):

   • docker-compose up -d frappe-mcp-server

4. Verify the server is running:

   • docker ps
   • Check container logs for any errors: docker logs -f <container_id>

If you are not using Docker Compose, ensure you provide the same environment variables and run the container with the appropriate image and command as described in the mcp_config section above.

Notes and tips:

• Ensure your .env (or equivalent environment variables) includes FRAPPE_SITE_URL, FRAPPE_API_KEY, and FRAPPE_API_SECRET to authenticate against your Frappe site.
• The MCP server expects network access from the container to your Frappe instance; configure networking accordingly if your Frappe site is private or uses a VPN.
• If you update credentials, restart the container to apply changes.
• Logs are your best friend for troubleshooting; inspect container logs with docker logs -f <container_id>.
• This server is Python-based (uv) and is designed to run in a containerized environment; if you prefer a non-Docker setup, you would adapt the step to run via uvx + local Python environment, ensuring dependencies are installed.
• The environment variables and endpoints can be extended in the deployment script or docker-compose file if your deployment requires additional configuration.