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)

Endpoint	Method	Description
/api/method/erp_chatbot.api.mcp_chatgpt_tools	GET	List all available tools

Authenticated Endpoints

Endpoint	Method	Description
/api/method/erp_chatbot.api.mcp_chatgpt_execute	POST	Execute MCP tools
/api/method/erp_chatbot.api.get_financial_analysis	GET	P&L and financial reports
/api/method/erp_chatbot.api.get_sales_dashboard	GET	Sales analytics dashboard
/api/method/erp_chatbot.api.get_inventory_summary	GET	Inventory overview
/api/method/erp_chatbot.api.generate_chart	POST	Create data visualizations
/api/method/erp_chatbot.api.create_report	POST	Build custom reports
/api/method/erp_chatbot.api.get_dashboard_kpis	GET	Key performance indicators

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

File	Purpose
chatgpt_openapi.yaml	OpenAPI schema for ChatGPT
chatgpt_gpt_instructions.md	GPT behavior configuration
api.py	Backend API endpoints
mcp_server_sse.py	Standalone MCP server
QUICK_START.md	Quick setup guide
API_KEY_SETUP.md	Auth troubleshooting

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