Frappe Dev MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with powerful tools for Frappe/ERPNext development. This server enables AI assistants to help with creating DocTypes, running bench commands, managing apps, generating APIs, and performing database operations.

🚀 Features

• 📋 DocType Management: Create, modify, and analyze Frappe DocTypes with AI assistance
• ⚡ Bench Commands: Execute bench commands directly through AI conversations
• 📱 App Development: Create, install, and manage Frappe applications
• 🔗 API Generation: Generate custom API endpoints with proper error handling
• 🗄️ Database Operations: Run migrations, execute queries, and manage data
• 📊 Reporting: Generate reports and financial statements
• 🎨 UI Components: Create Vue.js components using frappe-ui
• 📈 Document Operations: Full CRUD operations on Frappe documents

📦 Installation

Via NPM (Recommended)

npm install -g frappe-dev-mcp-server

Via GitHub

git clone https://github.com/SajmustafaKe/frappe-dev-mcp-server.git
cd frappe-dev-mcp-server
npm install
npm run build

⚙️ Configuration

Environment Variables

Set the FRAPPE_PATH environment variable to point to your Frappe bench directory:

export FRAPPE_PATH="/path/to/your/frappe/bench"

If not set, it defaults to the current working directory.

🔧 Usage

With Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "frappe-dev": {
      "command": "npx",
      "args": ["frappe-dev-mcp-server"],
      "env": {
        "FRAPPE_PATH": "/path/to/your/frappe/bench"
      }
    }
  }
}

With Other MCP Clients

The server implements the standard MCP protocol over stdio transport:

# Global installation
npx frappe-dev-mcp-server

# Local build
node dist/index.js

With VS Code + MCP Extension

Add to your MCP settings:

{
  "servers": {
    "frappe-dev": {
      "command": "npx",
      "args": ["frappe-dev-mcp-server"],
      "env": {
        "FRAPPE_PATH": "/path/to/your/frappe/bench"
      }
    }
  }
}

🛠️ Available Tools

📋 DocType Operations

frappe_create_doctype

Creates a new Frappe DocType with JSON definition and Python controller.

Parameters:

• app_name (string): Name of the Frappe app
• doctype_name (string): Name of the DocType
• module (string): Module where DocType belongs
• fields (array): Field definitions with fieldname, label, fieldtype, etc.
• is_submittable (boolean): Whether the DocType is submittable
• is_child (boolean): Whether this is a child DocType

frappe_get_doctype_schema

Retrieves the complete schema/structure of a DocType.

frappe_get_doctype_list

Lists all available DocTypes in the system.

⚡ Bench Operations

frappe_run_bench_command

Executes bench commands for Frappe development.

Parameters:

• command (string): Bench command to execute
• site (string, optional): Site name
• cwd (string, optional): Working directory

📱 App Management

frappe_create_app

Creates a new Frappe app with proper structure.

frappe_install_app

Installs a Frappe app on a specific site.

frappe_get_app_structure

Retrieves the directory structure of a Frappe app.

🔗 API Development

frappe_create_api_endpoint

Creates custom API endpoints with proper error handling.

Parameters:

• app_name (string): Name of the Frappe app
• endpoint_name (string): Name of the API endpoint
• method (string): HTTP method (get, post, put, delete)
• code (string): Python code for the endpoint

🗄️ Database Operations

frappe_migrate_database

Runs database migrations for a site.

frappe_create_document

Creates a new document in the database.

frappe_get_document

Retrieves a document by DocType and name.

frappe_update_document

Updates an existing document.

frappe_delete_document

Deletes a document from the database.

frappe_list_documents

Lists documents with optional filtering.

💡 Example Usage

AI Conversation Examples

Creating a DocType

You: "Create a Customer Order DocType in my_app with customer link, order date, and total amount fields"

AI: I'll create the Customer Order DocType for you.

The AI will use frappe_create_doctype with:

{
  "app_name": "my_app",
  "doctype_name": "Customer Order",
  "module": "Orders",
  "fields": [
    {
      "fieldname": "customer",
      "label": "Customer", 
      "fieldtype": "Link",
      "options": "Customer",
      "reqd": true
    },
    {
      "fieldname": "order_date",
      "label": "Order Date",
      "fieldtype": "Date",
      "reqd": true
    },
    {
      "fieldname": "total_amount",
      "label": "Total Amount",
      "fieldtype": "Currency",
      "reqd": true
    }
  ]
}

Running Bench Commands

You: "Migrate the database for my_site.local"

AI: I'll run the migration for you.

Uses frappe_run_bench_command:

{
  "command": "migrate",
  "site": "my_site.local"
}

Creating API Endpoints

You: "Create an API endpoint to get customer orders"

AI: I'll create a custom API endpoint for customer orders.

📊 Reporting and Analytics

The server includes tools for generating financial statements, running query reports, and creating custom reports that integrate seamlessly with ERPNext's reporting system.

🏗️ Development

Local Development

1. Clone the repository:

   git clone https://github.com/SajmustafaKe/frappe-dev-mcp-server.git
   cd frappe-dev-mcp-server

2. Install dependencies:

   npm install

3. Make your changes in the src/ directory

4. Build and test:

   npm run build
   npm run dev  # For development mode

Testing

Test the server with any MCP-compatible client:

# Test tool listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

# Test a specific tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"frappe_get_doctype_list","arguments":{"site":"your-site"}}}' | node dist/index.js

📋 Requirements

• Node.js: Version 18 or higher
• Frappe Framework: Properly configured bench environment
• Database: MariaDB/MySQL with Frappe sites
• Permissions: Access to bench commands and site directories

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Model Context Protocol
• Frappe Framework
• ERPNext
• MCP Registry

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue if your problem isn't already reported
3. Provide detailed information about your Frappe setup and the issue

Made with ❤️ for the Frappe/ERPNext community