Frappe MCP

A Model Context Protocol (MCP) designed to help AI agents understand and work with Frappe applications. This tool provides semantic analysis and exploration capabilities for Frappe codebases.

Frappe MCP in Action

Features

Automatic Analysis: Automatically analyzes Frappe application structure on server startup when files change
DocType Management: Complete DocType lifecycle including information retrieval, template generation, and database schema access
Code Analysis: Symbol search, function signature extraction, and field usage tracking
Testing Integration: Execute Frappe unit tests for modules or specific DocTypes
Development Tools: Generate boilerplate code for DocTypes and web pages
Database Access: Direct MariaDB query execution and bench command integration
Relationship Mapping: Analyze and visualize DocType relationships and dependencies
MCP Integration: Standard MCP server interface for AI agent communication

Tools Available

Core Analysis Tools

find_symbols: Search for symbols across the app source files with fuzzy matching support
find_field_usage: Search for references to specific DocType fields in code
search_frappe_docs: Search embedded Frappe framework documentation with fuzzy matching and category filtering
read_frappe_doc: Read the full content of a specific Frappe documentation file by ID

DocType Management

get_doctype: Get comprehensive DocType information by name (e.g., "Sales Invoice")
get_doctype_db_schema: Get the database schema for a specific DocType
create_doctype: Generate boilerplate DocType structure with JSON metadata, Python controller, and JS form files
analyze_links: Analyze and map relationships between DocTypes by examining Link, Table, and Select fields
list_doctypes: List all available DocTypes in the current Frappe app, optionally filtered by module

Development & Testing

create_web_page: Generate boilerplate web page files with HTML, CSS, and JavaScript structure
create_custom_page: Generate Frappe custom page scaffolding with forms and backend API endpoints
create_test_template: Create test template files for a Frappe DocType with proper test structure
create_report: Create report template files (Script Report, Query Report, or Report Builder)
run_tests: Execute unit tests for specific modules, DocTypes, or entire app using bench run-tests

System Integration

run_bench_command: Run arbitrary bench command with arguments (e.g., migrate, install-app)
run_db_command: Execute SQL queries via bench mariadb command
bench_execute: Execute Frappe functions via bench execute command with optional args and kwargs

Installation & Usage

Prerequisites

Rust (latest stable version)
Frappe application codebase to analyze

Setup

Clone and build:

git clone https://github.com/anvie/frappe-mcp.git
cd frappe-mcp
cargo build --release

Configure your Frappe app by creating a frappe-mcp.conf file (see Configuration section below)
Run the MCP server:

cargo run -- --config frappe-mcp.conf run

The server will automatically analyze your Frappe application on first run or when source files change.

Use with Claude Code:

claude mcp add frappe_mcp ./target/release/frappe_mcp run

Make sure you have frapppe-mcp.conf file in the same directory where you run the claude.

Testing

Use the MCP Inspector to test the server:

cargo build --release
npx @modelcontextprotocol/inspector -- ./target/release/frappe_mcp --config frappe-mcp.conf run

Available test methods include all tools listed above: find_symbols, get_doctype, create_doctype, run_tests, analyze_links, create_web_page, find_field_usage, run_bench_command, get_doctype_db_schema, run_db_command, search_frappe_docs, read_frappe_doc, list_doctypes, create_custom_page, create_test_template, create_report, bench_execute

Configuration

Create a frappe-mcp.conf file to configure the server. Example configuration:

frappe_bench_dir = "/path/to/frappe-bench"
app_relative_path = "your-app-name"
app_name = "Your App Name"
site = "yoursite.localhost"

Configuration parameters:

frappe_bench_dir: Path to your Frappe bench directory
app_relative_path: Name of your app directory within the bench/apps folder
app_name: Display name of your app
site: Frappe site name (defaults to "frontend" if not specified)

Manual Analysis (Optional)

While the server automatically analyzes your app on startup, you can also run analysis manually:

cargo run -- --config frappe-mcp.conf analyze --app-dir /path/to/frappe-bench/apps/your-app

This generates an analyzed_output.dat file with structured information about your app's modules and DocTypes.

CLI Tools

Functool Command

The functool subcommand allows direct execution of MCP functions from the command line, useful for testing and debugging:

# Get DocType information
cargo run -- functool get-doctype "Sales Invoice"
cargo run -- functool get-doctype "Sales Invoice" json  # JSON output only

# List all DocTypes in a module
cargo run -- functool list-doctypes "Selling"

# Search for symbols in the codebase
cargo run -- functool find-symbols "get_doc" "accounts" true 10

# Find field usage
cargo run -- functool find-field-usage "Sales Invoice" "customer" 20

# Run bench commands
cargo run -- functool run-bench-command "list-apps"

Available functions:

get-doctype: Get comprehensive DocType information
list-doctypes: List DocTypes, optionally filtered by module
find-symbols: Search for function/class symbols in code
find-field-usage: Find where DocType fields are referenced
run-bench-command: Execute bench commands

Documentation Search

The server includes built-in CLI commands for searching embedded Frappe documentation:

Note: Documents are referenced by short hash-based IDs (e.g., "48b014") rather than file paths to avoid confusion with filesystem operations. Use search-docs to find document IDs.

Search Documentation

# Search for documentation about DocTypes
cargo run -- search-docs "DocType" --category doctypes --limit 5

# Fuzzy search for API documentation
cargo run -- search-docs "databse" --category api --fuzzy

# Search across all categories
cargo run -- search-docs "getting started"

Read Specific Document

# First, search to get document IDs
cargo run -- search-docs "Frappe Framework Documentation" --limit=1

# Then read the document using its ID
cargo run -- read-doc "48b014"  # ID for main documentation index

# Read DocType creation guide
cargo run -- read-doc "3b7f1e"  # ID for creating_doctypes.md

# Read API documentation
cargo run -- read-doc "454ba4"  # ID for database_api.md

CLI Options

--category: Filter by category (doctypes, api, tutorial)
--fuzzy: Enable fuzzy search (default: true)
--limit: Maximum number of results (default: 10)

Author: Robin Syihab