🤖 AI MCP - Universal Dynamic MCP Server for Frappe & ERPNext v16

ai_mcp is a native Frappe application that packages an enterprise-grade dynamic Model Context Protocol (MCP) server for Frappe and ERPNext v16. It exposes 36 dynamic tools, FastMCP Resources, pre-built Prompts, Server-Sent Events (SSE) transport, and real-time Document Event Webhooks across all 816+ system DocTypes.

---

🌟 Enterprise Features

1. Single-Site & Multi-Site Single Install
   • Seamlessly installs on any Frappe site with standard bench install-app ai_mcp. Auto-initializes AI MCP Settings and exports fixtures out of the box.
2. Built-in Bench CLI Command
   • Run the server for any site directly via bench --site <site-name> mcp-server --transport [stdio|sse].
3. 816+ DocTypes Dynamic Operations
   • Query, fetch, create, update, bulk-update, and delete documents dynamically across all modules (Accounts, Stock, Selling, Buying, Manufacturing, Projects, Custom).
4. Role-Based Tool Permission Matrix
   • Restricts high-risk tools (run_sql_query, delete_document, create_custom_field, bulk_update_documents) to System Manager or AI Admin roles or explicit frappe.has_permission() checks.
5. Rate-Limiting & Payload Truncation Guardrails
   • Redis-backed rate limiting (default 60 req/min) and automatic response payload truncation (default 100KB limit).
6. Asynchronous Non-Blocking Audit Logging
   • Offloads audit logging to background queues (frappe.enqueue) to eliminate DB write overhead during tool execution.
7. FastMCP Resources & Prompts
   • Dynamic resources (frappe://system-health/{site}, frappe://kpi-summary/{site}, frappe://doctypes/{site}) and AI business prompts (financial_summary_prompt, stock_reorder_prompt, procurement_audit_prompt).
8. Real-Time Document Webhooks
   • Document event triggers (Purchase Order, Material Request) sending real-time webhooks to AI agents upon document submission.

---

🚀 Installation & Setup

1. Install App on Any Site

cd ~/frappe-bench
bench get-app ai_mcp # or local path / git repository
bench --site site1.local install-app ai_mcp

2. Launch MCP Server for Any Site

Stdio Mode:

bench --site site1.local mcp-server

SSE Streaming Mode:

bench --site site1.local mcp-server --transport sse --port 8000

---

🌐 REST API & SSE Endpoints

Endpoint	Method	Description
/api/method/ai_mcp.api.execute_tool	POST	Execute any MCP tool over HTTP REST API.
/api/method/ai_mcp.api.list_available_tools	GET	List available tools and docstrings.
/api/method/ai_mcp.api.sse_endpoint	GET/POST	Get SSE connection URLs and streaming headers.

---

🛠️ Complete MCP Tools Reference (36 Tools)

Tool Category	Function Name	Description
Discovery & Schema	list_doctypes	List active DocTypes filtered by module or search keyword.
	get_doctype_meta	Fetch complete schema definition, fieldtypes, and child tables.
	get_doctype_relations	Map incoming/outgoing Link fields and child tables (ER-diagram).
Schema Building	create_custom_field	Create custom field dynamically with custom_ prefix (Restricted).
	add_property_setter	Adjust standard field properties without editing core files.
Universal CRUD	list_documents	Query & list documents for any DocType with filters/sorting.
	get_document	Fetch full record details for any document.
	create_document	Insert new document record for any DocType.
	update_document	Update fields on existing record.
	bulk_update_documents	Bulk update multiple records in a single transaction (Restricted).
	delete_document	Delete record for any DocType (Restricted).
	import_csv_data	Parse & import base64-encoded CSV dataset.
Automation Bots	check_low_stock_and_reorder	Scan low stock items and auto-create draft Material Requests.
	diagnose_and_clean_errors	Group Error Logs by method and optionally purge old logs.
	find_duplicate_records	Detect duplicate column values for any DocType safely.
	auto_approve_workflow	Auto-apply 'Approve' action on Workflow-enabled documents.
KPIs & Finance	get_kpi_summary	Compute receivables, monthly sales, pending orders, item count.
	get_currency_exchange_rate	Get live/historical exchange rate between currencies.
Communications	send_email_notification	Send email via queue or log to Communication DocType.
	attach_file	Attach base64 file or URL to any document record.
Transactions	commit_transaction	Commit current DB transaction.
	rollback_transaction	Roll back current DB transaction.
PDF & Printing	generate_print_pdf	Render PDF/HTML preview for any document record.
Search & Auth	global_search	Keyword search across global index.
	check_user_permission	Check user read/write/create/delete permissions.
	search_link_options	Autocomplete options for Link fields.
Methods & Background	call_whitelisted_method	Execute any @frappe.whitelist() backend method.
	enqueue_background_job	Enqueue background job to RQ workers with Redis fallback.
Lifecycle & Reports	submit_document	Submit submittable document (docstatus 0 ➔ 1).
	cancel_document	Cancel submitted document (docstatus 1 ➔ 2).
	apply_workflow_action	Advance document state via Workflow action.
	execute_report	Run built-in Frappe/ERPNext report.
	export_report_to_excel	Export report directly to Excel (.xlsx) file.
	get_system_health_status	Check DB status, error logs, installed apps, scheduler.
	get_document_count	Get total record count for any DocType.
	run_sql_query	Read-only SQL SELECT queries with injection guardrails (Restricted).

mcp-erpnext