ERPNext MCP Server for ChatGPT

A complete Model Context Protocol (MCP) integration that connects ChatGPT to your ERPNext instance, enabling AI-powered business analytics, report generation, and document management.

What This Does

This integration allows ChatGPT to:

• Generate financial reports (P&L, Balance Sheet, Cash Flow)

• Analyze sales trends and customer data

• Check inventory and stock levels

• Access HR and employee information

• Create and update ERPNext documents

• Build custom dashboards and visualizations

Project Structure

/home/frappe/test.bench/apps/erp_chatbot/
├── erp_chatbot/
│   ├── api.py                    # Main API endpoints
│   ├── mcp_server_sse.py         # Standalone MCP server with SSE transport
│   └── hooks.py                  # Frappe app hooks
├── chatgpt_openapi.yaml          # OpenAPI schema for ChatGPT Actions
├── chatgpt_gpt_instructions.md   # GPT behavior instructions
├── QUICK_START.md               # 5-minute setup guide
├── API_KEY_SETUP.md             # Authentication troubleshooting
└── pyproject.toml               # Dependencies

Quick Start (5 Minutes)

Step 1: Install Dependencies

cd /home/frappe/test.bench
./env/bin/pip install mcp sse-starlette starlette uvicorn

Step 2: Get ERPNext API Key

1. Login to ERPNext as Administrator

2. Go to User → API Access

3. Click Generate Keys

4. Copy API Key and API Secret

Step 3: Create ChatGPT GPT

1. Go to chat.openai.com

2. Click Explore GPTs → Create

3. Name: ERPNext Assistant

Step 4: Configure GPT

Instructions Tab:

• Copy contents from chatgpt_gpt_instructions.md

• Paste in Instructions box

Actions Tab:

1. Click Add actions

2. Import schema: chatgpt_openapi.yaml

3. Authentication:

   • Type: API Key

   • Key: Authorization

   • Value: Bearer YOUR_API_KEY:YOUR_API_SECRET

   • Auth Type: Bearer

Step 5: Test

Ask your GPT:

"What companies are available?"
"Show me this month's sales"

Available API Endpoints

Public Endpoints (No Auth Required)

Authenticated Endpoints

Available Tools

Reporting Tools

• get_report_data - Execute standard ERPNext reports

• get_sales_analytics - Sales trends with date filtering

• get_financial_analysis - P&L statements with charts

Data Query Tools

• get_list_data - Query any DocType with filters

• get_document - Fetch single document

• get_companies - List available companies

• get_inventory_summary - Stock levels and overview

Document Management

• create_document - Create new ERPNext records

• update_document - Modify existing records

Analytics & Visualization

• generate_chart - Create bar, pie, line charts

• create_report - Build custom reports

• get_dashboard_kpis - Business KPIs

Authentication

API Key Format

Authorization: Bearer api_key:api_secret

Example:

Authorization: Bearer d4e8f2c1b5a9:8f3e2d1c9b7a5f4e

Getting API Keys

1. ERPNext → Users → Select your user

2. Scroll to API Access section

3. Click Generate Keys

4. Save both API Key and API Secret

Important: API Secret is shown only once. Save it immediately!

Standalone MCP Server

Run the MCP server independently:

cd /home/frappe/test.bench
./env/bin/python apps/erp_chatbot/erp_chatbot/mcp_server_sse.py

Server starts on http://localhost:8000

Endpoints

• GET /mcp/sse - SSE connection

• POST /mcp/messages - MCP messages

• GET /health - Health check

Usage Examples

Query Sales Data

{
  "tool": "get_list_data",
  "arguments": {
    "doctype": "Sales Invoice",
    "filters": {"status": "Overdue"},
    "fields": ["name", "customer", "grand_total"],
    "limit": 20
  }
}

Create a Customer

{
  "tool": "create_document",
  "arguments": {
    "doctype": "Customer",
    "data": {
      "customer_name": "New Customer Ltd",
      "customer_type": "Company",
      "territory": "Pakistan"
    }
  }
}

Generate P&L Report

{
  "tool": "get_report_data",
  "arguments": {
    "report_name": "Profit and Loss Statement",
    "filters": {
      "company": "Your Company",
      "fiscal_year": "2024-2025"
    }
  }
}

Create a Chart

{
  "chart_type": "bar",
  "labels": ["Jan", "Feb", "Mar", "Apr"],
  "values": [10000, 15000, 12000, 18000],
  "title": "Monthly Sales"
}

Troubleshooting

401 Authentication Error

• Verify API Key format: Bearer key:secret (with colon)

• Check user has proper permissions

• Ensure API keys are generated correctly

Tools Not Showing

• Refresh schema in ChatGPT Actions

• Check chatgpt_openapi.yaml is properly uploaded

• Verify server URL is correct

Connection Failed

• Check ERPNext server is running

• Verify domain URL in schema

• Test endpoint directly in browser

Support

For issues:

1. Check Frappe logs: bench --site yoursite.com logs

2. Verify API permissions

3. Test endpoints directly:

   https://yoursite.com/api/method/erp_chatbot.api.mcp_chatgpt_tools

Files Reference

Security Notes

• Keep API keys secret and secure

• Use HTTPS in production

• Regularly rotate API keys

• Grant minimum required permissions

Ready to Use!

Your ChatGPT is now connected to ERPNext. Start asking business questions!

Example queries:

• "Show me overdue invoices"

• "What's our inventory status?"

• "Create a sales order for ABC Corp"

• "Generate P&L for Q1 2024"

Built for test.bench / erp.site.com

Created by Ibni for ERPNext MCP Server

License

mit