MCP-Frappe/CONNECT.md

# 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.