# erpnext-fast-mcp-server

A [FastMCP](https://gofastmcp.com) server that exposes generic ERPNext / Frappe
DocType operations as MCP tools, so any MCP-compatible client (Claude Desktop,
Claude Code, etc.) can read and write data in an ERPNext site over its REST API.

## Tools

- `get_document(doctype, name)` — fetch a single document
- `list_documents(doctype, filters, fields, order_by, limit, limit_start)` — search/list documents
- `create_document(doctype, data)` — create a document
- `update_document(doctype, name, data)` — update fields on a document
- `delete_document(doctype, name)` — delete a document
- `get_doctype_meta(doctype)` — fetch a DocType's field/schema definition
- `get_count(doctype, filters)` — count documents matching filters
- `run_report(report_name, filters)` — run a Query/Script report

These are generic, so they work against any DocType (Customer, Sales Invoice,
Item, Stock Entry, etc.) without hardcoding business objects.

## Setup

1. Install dependencies (using [uv](https://docs.astral.sh/uv/)):

   ```bash
   uv sync
   ```

2. Get API credentials from your Frappe/ERPNext site: **User → API Access →
   Generate Keys**. Copy the API Key and API Secret shown (the secret is only
   displayed once).

3. Copy `.env.example` to `.env` and fill in your values:

   ```bash
   cp .env.example .env
   ```

   ```
   FRAPPE_URL=https://your-site.frappe.cloud
   FRAPPE_API_KEY=your-api-key
   FRAPPE_API_SECRET=your-api-secret
   ```

   `.env` is git-ignored — never commit real credentials.

4. Run the server directly to check it starts:

   ```bash
   uv run erpnext-mcp
   ```

## Using with Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "erpnext": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/erpnext-fast-mcp-server", "erpnext-mcp"],
      "env": {
        "FRAPPE_URL": "https://your-site.frappe.cloud",
        "FRAPPE_API_KEY": "your-api-key",
        "FRAPPE_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

Alternatively, keep credentials only in `.env` (not in the client config) and
omit the `env` block above — `python-dotenv` will load `.env` from the
project directory at startup.

## Security notes

- Never commit `.env` or hardcode API keys/secrets in source.
- Scope the Frappe user's role/permissions to the minimum needed — the MCP
  tools inherit whatever permissions the API key's user has on the site.
- `delete_document` is irreversible; consider removing it from the tool list
  if you don't want an MCP client to be able to delete records.