feat: Update environment variables and enhance API documentation for Frappe connection
This commit is contained in:
parent
2be34e75bf
commit
008f6cfcb9
86
.env
86
.env
@ -1,47 +1,51 @@
|
|||||||
# Frappe instance URL (your VPS / Docker host)
|
MCP_HOST=0.0.0.0
|
||||||
# If using a domain: https://erp.yourdomain.com
|
MCP_PORT=16000
|
||||||
# If using Docker with port mapping: http://YOUR_VPS_IP:8000
|
MCP_BEARER_TOKEN=MetaFrappe@2026
|
||||||
FRAPPE_URL=http://147.93.40.215:10009/
|
|
||||||
|
|
||||||
# API credentials — generate in Frappe: Settings > My Account > API Access
|
# # Frappe instance URL (your VPS / Docker host)
|
||||||
FRAPPE_API_KEY=2650fa15dc9393f
|
# # If using a domain: https://erp.yourdomain.com
|
||||||
FRAPPE_API_SECRET=766ad5af8577685
|
# # If using Docker with port mapping: http://YOUR_VPS_IP:8000
|
||||||
|
# FRAPPE_URL=http://147.93.40.215:10009/
|
||||||
|
|
||||||
# For multi-site Docker setups (optional) — the site name e.g. "site1.localhost"
|
# # API credentials — generate in Frappe: Settings > My Account > API Access
|
||||||
FRAPPE_SITE_NAME=
|
# FRAPPE_API_KEY=2650fa15dc9393f
|
||||||
|
# FRAPPE_API_SECRET=766ad5af8577685
|
||||||
|
|
||||||
# Set to true to block all write/delete operations (safe read-only mode)
|
# # For multi-site Docker setups (optional) — the site name e.g. "site1.localhost"
|
||||||
READ_ONLY_MODE=false
|
# FRAPPE_SITE_NAME=
|
||||||
|
|
||||||
# HTTP timeout in seconds for API calls
|
# # Set to true to block all write/delete operations (safe read-only mode)
|
||||||
REQUEST_TIMEOUT=30
|
# READ_ONLY_MODE=false
|
||||||
|
|
||||||
ENABLED_MODULES=foundation,document_inspect,analytics
|
# # HTTP timeout in seconds for API calls
|
||||||
|
# REQUEST_TIMEOUT=30
|
||||||
|
|
||||||
# ── Module on/off switches ───────────────────────────────────────────────────
|
# ENABLED_MODULES=foundation,document_inspect,analytics
|
||||||
# Uncomment a line to disable that module (all others stay ON)
|
|
||||||
# MODULE_FOUNDATION=false
|
# # ── Module on/off switches ───────────────────────────────────────────────────
|
||||||
# MODULE_DOCTYPES=false
|
# # Uncomment a line to disable that module (all others stay ON)
|
||||||
# MODULE_DOCUMENTS=false
|
# # MODULE_FOUNDATION=false
|
||||||
# MODULE_DOCUMENT_INSPECT=false
|
# # MODULE_DOCTYPES=false
|
||||||
# MODULE_DOCUMENT_LIFECYCLE=false
|
# # MODULE_DOCUMENTS=false
|
||||||
# MODULE_CUSTOM_FIELDS=false
|
# # MODULE_DOCUMENT_INSPECT=false
|
||||||
# MODULE_SCRIPTS=false
|
# # MODULE_DOCUMENT_LIFECYCLE=false
|
||||||
# MODULE_WORKFLOW_TOOLS=false
|
# # MODULE_CUSTOM_FIELDS=false
|
||||||
# MODULE_ANALYTICS=false
|
# # MODULE_SCRIPTS=false
|
||||||
# MODULE_REPORTS=false
|
# # MODULE_WORKFLOW_TOOLS=false
|
||||||
# MODULE_PRINT_FORMATS=false
|
# # MODULE_ANALYTICS=false
|
||||||
# MODULE_BULK_OPS=false
|
# # MODULE_REPORTS=false
|
||||||
# MODULE_BUSINESS_ACTIONS=false
|
# # MODULE_PRINT_FORMATS=false
|
||||||
# MODULE_USERS=false
|
# # MODULE_BULK_OPS=false
|
||||||
# MODULE_ADMIN=false
|
# # MODULE_BUSINESS_ACTIONS=false
|
||||||
# MODULE_PROPERTY_SETTERS=false
|
# # MODULE_USERS=false
|
||||||
# MODULE_NAMING_SERIES=false
|
# # MODULE_ADMIN=false
|
||||||
# MODULE_FILES=false
|
# # MODULE_PROPERTY_SETTERS=false
|
||||||
# MODULE_ACTIVITY=false
|
# # MODULE_NAMING_SERIES=false
|
||||||
# MODULE_DASHBOARDS=false
|
# # MODULE_FILES=false
|
||||||
# MODULE_WEBHOOKS=false
|
# # MODULE_ACTIVITY=false
|
||||||
# MODULE_EMAIL_TEMPLATES=false
|
# # MODULE_DASHBOARDS=false
|
||||||
# MODULE_TRANSLATIONS=false
|
# # MODULE_WEBHOOKS=false
|
||||||
# MODULE_SCHEDULER=false
|
# # MODULE_EMAIL_TEMPLATES=false
|
||||||
# MODULE_GOVERNANCE=false
|
# # MODULE_TRANSLATIONS=false
|
||||||
|
# # MODULE_SCHEDULER=false
|
||||||
|
# # MODULE_GOVERNANCE=false
|
||||||
|
|||||||
277
CONNECT.md
Normal file
277
CONNECT.md
Normal file
@ -0,0 +1,277 @@
|
|||||||
|
# Frappe MCP — Connection Guide
|
||||||
|
|
||||||
|
**Server:** `https://mcp-frappe.metatronhost.com/sse`
|
||||||
|
**Server Token:** `MetaFrappe@2026`
|
||||||
|
|
||||||
|
You also need your own Frappe/ERPNext credentials to pass along with each connection:
|
||||||
|
|
||||||
|
| Header | Value |
|
||||||
|
|---|---|
|
||||||
|
| `Authorization` | `Bearer MetaFrappe@2026` |
|
||||||
|
| `X-Frappe-URL` | Your ERPNext URL e.g. `https://erp.yourcompany.com` |
|
||||||
|
| `X-Frappe-API-Key` | Your Frappe API Key |
|
||||||
|
| `X-Frappe-API-Secret` | Your Frappe API Secret |
|
||||||
|
| `X-Frappe-Site-Name` | *(optional)* Only for multi-site Docker setups |
|
||||||
|
|
||||||
|
> **How to get your Frappe API Key & Secret:**
|
||||||
|
> Login to ERPNext → top-right avatar → **My Profile** → **API Access** → **Generate Keys**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Claude Desktop
|
||||||
|
|
||||||
|
Edit your Claude Desktop config file:
|
||||||
|
|
||||||
|
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||||
|
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
||||||
|
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"frappe": {
|
||||||
|
"url": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Restart Claude Desktop after saving. You should see **frappe** appear in the tools panel (hammer icon).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Claude Code (CLI)
|
||||||
|
|
||||||
|
### Option A — Project-level (only this project)
|
||||||
|
|
||||||
|
Create `.mcp.json` in your project root:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"frappe": {
|
||||||
|
"url": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option B — Global (available in all projects)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
claude mcp add frappe \
|
||||||
|
--transport sse \
|
||||||
|
--url "https://mcp-frappe.metatronhost.com/sse" \
|
||||||
|
--header "Authorization: Bearer MetaFrappe@2026" \
|
||||||
|
--header "X-Frappe-URL: https://erp.yourcompany.com" \
|
||||||
|
--header "X-Frappe-API-Key: your_api_key" \
|
||||||
|
--header "X-Frappe-API-Secret: your_api_secret"
|
||||||
|
```
|
||||||
|
|
||||||
|
Verify it's connected:
|
||||||
|
```bash
|
||||||
|
claude mcp list
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Cursor
|
||||||
|
|
||||||
|
Open **Cursor Settings** → **MCP** → **Add new MCP server**
|
||||||
|
|
||||||
|
Or edit `~/.cursor/mcp.json` (create if it doesn't exist):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"frappe": {
|
||||||
|
"url": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Restart Cursor. The Frappe tools will appear in Cursor's AI chat context.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. VS Code (GitHub Copilot — MCP extension)
|
||||||
|
|
||||||
|
Install the **MCP extension** from VS Code marketplace first.
|
||||||
|
|
||||||
|
Then edit VS Code `settings.json` (`Ctrl+Shift+P` → *Open User Settings JSON*):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcp.servers": {
|
||||||
|
"frappe": {
|
||||||
|
"url": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Or via **workspace** `.vscode/settings.json` (per-project):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcp.servers": {
|
||||||
|
"frappe": {
|
||||||
|
"url": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Windsurf (Codeium)
|
||||||
|
|
||||||
|
Edit `~/.codeium/windsurf/mcp_config.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"frappe": {
|
||||||
|
"serverUrl": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Continue.dev
|
||||||
|
|
||||||
|
Edit `~/.continue/config.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": [
|
||||||
|
{
|
||||||
|
"name": "frappe",
|
||||||
|
"transport": {
|
||||||
|
"type": "sse",
|
||||||
|
"url": "https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
"requestOptions": {
|
||||||
|
"headers": {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Any Custom App (OpenAI / Anthropic SDK)
|
||||||
|
|
||||||
|
Use any MCP client library and connect via SSE:
|
||||||
|
|
||||||
|
```python
|
||||||
|
import httpx
|
||||||
|
|
||||||
|
headers = {
|
||||||
|
"Authorization": "Bearer MetaFrappe@2026",
|
||||||
|
"X-Frappe-URL": "https://erp.yourcompany.com",
|
||||||
|
"X-Frappe-API-Key": "your_api_key",
|
||||||
|
"X-Frappe-API-Secret": "your_api_secret",
|
||||||
|
}
|
||||||
|
|
||||||
|
# SSE endpoint
|
||||||
|
response = httpx.get(
|
||||||
|
"https://mcp-frappe.metatronhost.com/sse",
|
||||||
|
headers=headers,
|
||||||
|
timeout=None
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verifying the Connection
|
||||||
|
|
||||||
|
You can test the server is reachable from a terminal:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -N \
|
||||||
|
-H "Authorization: Bearer MetaFrappe@2026" \
|
||||||
|
-H "X-Frappe-URL: https://erp.yourcompany.com" \
|
||||||
|
-H "X-Frappe-API-Key: your_api_key" \
|
||||||
|
-H "X-Frappe-API-Secret: your_api_secret" \
|
||||||
|
https://mcp-frappe.metatronhost.com/sse
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: an SSE stream starting with `event: endpoint` data.
|
||||||
|
|
||||||
|
A `401` means wrong bearer token.
|
||||||
|
A `400` means missing Frappe credential headers.
|
||||||
|
A `200` stream means you're connected.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Available Tools (150+)
|
||||||
|
|
||||||
|
Once connected, the AI has access to tools across these categories:
|
||||||
|
|
||||||
|
| Category | Examples |
|
||||||
|
|---|---|
|
||||||
|
| Documents | create, read, update, delete, submit, cancel |
|
||||||
|
| DocTypes | list, inspect schema, create custom DocTypes |
|
||||||
|
| Search & Inspect | search, timeline, linked docs, count |
|
||||||
|
| Workflows | list transitions, execute approval, get state |
|
||||||
|
| Analytics | aggregate, dashboard data, PDF render, KPI |
|
||||||
|
| Bulk Operations | batch create/update/delete/submit |
|
||||||
|
| ERPNext Business | Sales, Purchase, Stock, HR, Support shortcuts |
|
||||||
|
| Users & Roles | create users, assign roles, set permissions |
|
||||||
|
| Admin | cache, system settings, scheduled jobs |
|
||||||
|
| Governance | dry-run, risk score, audit log, rollback |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Notes
|
||||||
|
|
||||||
|
- The bearer token `MetaFrappe@2026` controls access to the MCP server itself.
|
||||||
|
- Your Frappe API Key/Secret controls what you can do inside ERPNext — scoped to your user's permissions.
|
||||||
|
- All traffic is encrypted via HTTPS.
|
||||||
|
- Never share your Frappe API Secret publicly.
|
||||||
@ -66,6 +66,7 @@ def tools() -> list[Tool]:
|
|||||||
"values": {
|
"values": {
|
||||||
"type": "array",
|
"type": "array",
|
||||||
"description": "Parameterized values for %s placeholders",
|
"description": "Parameterized values for %s placeholders",
|
||||||
|
"items": {},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
|
|||||||
@ -27,7 +27,7 @@ def tools() -> list[Tool]:
|
|||||||
},
|
},
|
||||||
"field": {"type": "string", "description": "Field to aggregate e.g. 'grand_total'"},
|
"field": {"type": "string", "description": "Field to aggregate e.g. 'grand_total'"},
|
||||||
"group_by": {"type": "string", "description": "Field to group by e.g. 'customer'"},
|
"group_by": {"type": "string", "description": "Field to group by e.g. 'customer'"},
|
||||||
"filters": {"type": "array"},
|
"filters": {"type": "array", "items": {}},
|
||||||
"limit": {"type": "integer", "default": 50},
|
"limit": {"type": "integer", "default": 50},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
|
|||||||
@ -66,6 +66,7 @@ def tools() -> list[Tool]:
|
|||||||
},
|
},
|
||||||
"permissions": {
|
"permissions": {
|
||||||
"type": "array",
|
"type": "array",
|
||||||
|
"items": {"type": "object"},
|
||||||
"description": "List of permission rows. Defaults to System Manager full access.",
|
"description": "List of permission rows. Defaults to System Manager full access.",
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
|
|||||||
@ -22,7 +22,7 @@ def tools() -> list[Tool]:
|
|||||||
"properties": {
|
"properties": {
|
||||||
"doctype": {"type": "string"},
|
"doctype": {"type": "string"},
|
||||||
"query": {"type": "string", "description": "Search text"},
|
"query": {"type": "string", "description": "Search text"},
|
||||||
"filters": {"type": "array", "description": "Additional filter conditions"},
|
"filters": {"type": "array", "items": {}, "description": "Additional filter conditions"},
|
||||||
"fields": {"type": "array", "items": {"type": "string"}},
|
"fields": {"type": "array", "items": {"type": "string"}},
|
||||||
"limit": {"type": "integer", "default": 20},
|
"limit": {"type": "integer", "default": 20},
|
||||||
"order_by": {"type": "string", "default": "modified desc"},
|
"order_by": {"type": "string", "default": "modified desc"},
|
||||||
@ -104,7 +104,7 @@ def tools() -> list[Tool]:
|
|||||||
"required": ["doctype"],
|
"required": ["doctype"],
|
||||||
"properties": {
|
"properties": {
|
||||||
"doctype": {"type": "string"},
|
"doctype": {"type": "string"},
|
||||||
"filters": {"type": "array"},
|
"filters": {"type": "array", "items": {}},
|
||||||
},
|
},
|
||||||
},
|
},
|
||||||
),
|
),
|
||||||
|
|||||||
@ -23,6 +23,7 @@ def tools() -> list[Tool]:
|
|||||||
},
|
},
|
||||||
"filters": {
|
"filters": {
|
||||||
"type": "array",
|
"type": "array",
|
||||||
|
"items": {},
|
||||||
"description": "Filter list e.g. [[\"status\", \"=\", \"Open\"]]",
|
"description": "Filter list e.g. [[\"status\", \"=\", \"Open\"]]",
|
||||||
},
|
},
|
||||||
"limit": {"type": "integer", "default": 20},
|
"limit": {"type": "integer", "default": 20},
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user