# 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

```bash
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](https://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:

```bash
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
```json
{
  "tool": "get_list_data",
  "arguments": {
    "doctype": "Sales Invoice",
    "filters": {"status": "Overdue"},
    "fields": ["name", "customer", "grand_total"],
    "limit": 20
  }
}
```

### Create a Customer
```json
{
  "tool": "create_document",
  "arguments": {
    "doctype": "Customer",
    "data": {
      "customer_name": "New Customer Ltd",
      "customer_type": "Company",
      "territory": "Pakistan"
    }
  }
}
```

### Generate P&L Report
```json
{
  "tool": "get_report_data",
  "arguments": {
    "report_name": "Profit and Loss Statement",
    "filters": {
      "company": "Your Company",
      "fiscal_year": "2024-2025"
    }
  }
}
```

### Create a Chart
```json
{
  "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