MCP Server for Frappe

A secure, audit-logged Model Context Protocol (MCP) server for Frappe. This app allows you to expose specific DocTypes and operations to MCP clients (like AI agents) with strict granular permissions, ensuring secure and controlled access to your Frappe data.

Features

• Secure Authentication: dedicated MCP User access via Token or API Key.
• Granular Allowlist: Explicitly allow specific DocTypes and operations (Create, Read, Update, Delete).
• Field-Level Control: Restrict which fields can be read or written.
• Audit Logging: Every request is logged with latency, status, and payload summaries.
• Strict Validation: All filters and inputs are validated against the allowlist.

Installation

1. Get the app:

   bench get-app https://github.com/mascor/frappe-mcp-server
   

2. Install on your site:

   bench --site  install-app mcp_server
   

Configuration

1. Setup MCP User & Settings

You can use the included setup script to quickly configure the server with a default user and token:

bench --site  execute mcp_server.setup.setup_mcp

This will:

• Create a user [email protected] (if not exists).
• Generate a secure X-MCP-Token and save it in MCP Server Settings.
• Enable the MCP Server.

Alternatively, go to MCP Server Settings in Desk and configure manually.

2. Configure Allowlist

By default, no access is allowed. You must explicitly allow DocTypes.

1. Go to MCP Doctype Allowlist.
2. Create a new record for the DocType you want to expose (e.g., ToDo).
3. Check the operations you want to allow (Allow Read, Allow Create, etc.).
4. (Optional) restricting fields and filters in the child tables for tighter security.

Usage

The server exposes standard MCP tools via the API.

Authentication

The server supports API Key authentication (recommended for MCP clients).

Include the Authorization header in all requests.

Tools

mcp_ping

Health check and version info.

curl -X POST https:///api/method/mcp_server.api.ping \
     -H "Authorization: token :"

search_docs

Search for documents with filters.

{
    "doctype": "ToDo",
    "filters": {"status": "Open"}
}

create_doc

Create a new document.

{
    "doctype": "ToDo",
    "data": {
        "description": "New Task from MCP"
    }
}

update_doc

Update an existing document.

{
    "doctype": "ToDo",
    "name": "TODO-0001",
    "data": {
        "status": "Closed"
    }
}

Audit Log

Check MCP Audit Log in Desk to see a history of all requests, including success/failure status, latency, and diffs.

License

MIT

Quick Connect: MCP Client

To connect to this server from an AI Client (like Claude Desktop or Cursor), use the official Python Client:

frappe-mcp-client

Follow the installation and setup instructions in the client repository to get started.

Frappe MCP Server - Test Report

Available Commands

---

Test Results Summary

Section A: Standard DocType Operations

Section B: Filters and Fields

Section C: Edge Cases / Error Handling

Section D: Permissions

---

🎉 Final Result: 18/18 Tests Passed

---

Test Examples

1. ping

Check server connection status.

Response:

{
  "status": "ok",
  "site": "your-site.example.com",
  "user": "[email protected]"
}

---

2. get_meta

Get the structure of a DocType.

Request:

doctype: "ToDo"

Response:

{
  "doctype": "ToDo",
  "fields": [
    {
      "fieldname": "status",
      "label": "Status",
      "fieldtype": "Select",
      "options": "Open\\nClosed\\nCancelled",
      "reqd": 0,
      "default": "Open"
    },
    {
      "fieldname": "priority",
      "label": "Priority",
      "fieldtype": "Select",
      "options": "High\\nMedium\\nLow",
      "reqd": 0,
      "default": "Medium"
    },
    {
      "fieldname": "date",
      "label": "Due Date",
      "fieldtype": "Date",
      "reqd": 0,
      "default": "Today"
    },
    {
      "fieldname": "description",
      "label": "Description",
      "fieldtype": "Text Editor",
      "reqd": 1
    }
  ],
  "issingle": 0,
  "istable": 0
}

---

3. create_doc

Create a new document.

Request:

doctype: "ToDo"
data: {
  "status": "Open",
  "priority": "High",
  "description": "Test task created via MCP"
}

Response:

{
  "name": "abc123xyz",
  "owner": "[email protected]",
  "creation": "2026-01-21 10:18:41.295624",
  "modified": "2026-01-21 10:18:41.295624",
  "modified_by": "[email protected]",
  "docstatus": 0,
  "status": "Open",
  "priority": "High",
  "date": "2026-01-21",
  "description": "Test task created via MCP",
  "doctype": "ToDo"
}

---

4. search_docs

Search for documents with optional filters and fields.

Request (basic):

doctype: "ToDo"

Response:

[
  {"name": "todo001"},
  {"name": "todo002"},
  {"name": "todo003"}
]

Request (with filters and fields):

doctype: "ToDo"
filters: {"status": "Open"}
fields: ["name", "status", "priority", "description"]

Response:

[
  {
    "name": "todo001",
    "status": "Open",
    "priority": "Medium",
    "description": "Test task 1"
  },
  {
    "name": "todo002",
    "status": "Open",
    "priority": "High",
    "description": "Test task 2"
  }
]

---

5. get_doc

Get a specific document by name.

Request:

doctype: "ToDo"
name: "abc123xyz"

Response:

{
  "name": "abc123xyz",
  "owner": "[email protected]",
  "status": "Open",
  "priority": "High",
  "date": "2026-01-21",
  "description": "Test task created via MCP",
  "creation": "2026-01-21 10:18:41.295624",
  "modified": "2026-01-21 10:18:41.295624",
  "modified_by": "[email protected]",
  "docstatus": 0
}

---

6. update_doc

Update an existing document.

Request:

doctype: "ToDo"
name: "abc123xyz"
data: {
  "status": "Closed",
  "priority": "Low"
}

Response:

{
  "name": "abc123xyz",
  "owner": "[email protected]",
  "creation": "2026-01-21 10:18:41.295624",
  "modified": "2026-01-21 10:18:59.096886",
  "modified_by": "[email protected]",
  "docstatus": 0,
  "status": "Closed",
  "priority": "Low",
  "date": "2026-01-21",
  "description": "Test task created via MCP",
  "doctype": "ToDo"
}

---

7. delete_doc

Delete a document.

Request:

doctype: "ToDo"
name: "abc123xyz"

Response:

{
  "status": "deleted",
  "name": "abc123xyz"
}

Error Response (document not found):

HTTP 404 Not Found

---

Setup Requirements

1. Install the MCP Server app on your Frappe site

   bench get-app https://github.com/[repo]/frappe-mcp-server
   bench --site [your-site] install-app mcp_server
   

2. Create an API user (e.g., [email protected])

3. Generate API keys for the user

   • Go to User → API Access → Generate Keys

4. Assign appropriate roles to the API user (e.g., System Manager)

5. Configure the Allowlist

   • Go to “MCP Doctype Allowlist”
   • Add DocTypes you want to expose via MCP
   • Configure allowed operations (Read, Create, Update, Delete, Meta)

6. Configure the MCP client with the API credentials

---

Allowlist Configuration

The MCP Server uses an Allowlist to control which DocTypes are accessible. For each DocType you can configure:

---

Error Codes

---

Troubleshooting

---

Security Notes

• Only DocTypes explicitly added to the Allowlist are accessible
• Each operation (Read, Create, Update, Delete, Meta) must be explicitly enabled
• API authentication is required for all operations
• Consider restricting sensitive DocTypes (User, Role, etc.) in production

---

Security Audit Report

Overview

The Frappe MCP Server has undergone comprehensive security testing to ensure it is safe for production use. All 15 security tests have passed successfully.

---

Security Test Results

Authentication & Authorization

Injection Attacks

Data Protection

---

Security Features

1. Allowlist-Based Access Control

Only DocTypes explicitly added to the MCP Doctype Allowlist are accessible via the API. Each DocType can be configured with granular permissions:

• Allow Read (Get, Search)
• Allow Create
• Allow Update
• Allow Delete
• Allow Meta (Schema)

2. Automatic Sensitive Field Filtering

The following fields are automatically removed from all API responses, regardless of user permissions or Allowlist configuration:

• api_key
• api_secret
• password
• new_password
• reset_password_key

This server-side filter prevents credential leakage even if the User DocType is in the Allowlist.

3. Input Sanitization

• SQL Injection Protection: All user inputs are parameterized through Frappe’s ORM
• XSS Protection: HTML content is automatically sanitized (e.g., `"})

Result: Content sanitized to “<script>alert(‘XSS’)</script>”

### Path Traversal

```python
# Attempted attack
get_doc(doctype="../../../etc/passwd", name="root")

# Result: 403 Forbidden (DocType not in Allowlist)

Privilege Escalation

# Attempted attack
update_doc(doctype="User", name="[email protected]", data={"user_type": "Administrator"})

# Result: 403 Forbidden (Update not allowed on User DocType)

---

Compliance Summary

---

Final Result

╔══════════════════════════════════════════════════════════════╗
║                    SECURITY AUDIT PASSED                     ║
║                                                              ║
║                    15/15 Tests Successful                    ║
║                                                              ║
║          ✅ Ready for Production Deployment                  ║
╚══════════════════════════════════════════════════════════════╝