Skip to main content
Glama
Pennylane MCP
by wanadev
README.md
# pennylane-mcp

MCP server for the [Pennylane v2 API](https://pennylane.readme.io/), auto-generated from the official OpenAPI spec. Exposes **183 tools** covering customers, invoices, suppliers, products, transactions, ledger entries, journals, quotes, categories, and more.

## Install & run

Requires Node.js 22.12+.

### From npm (once published)

```bash
npx -y @wanadev/pennylane-mcp
```

### From source

```bash
git clone <this-repo> && cd pennylane-mcp
npm install   # runs `npm run generate && npm run build` via prepare
node build/server.js
```

### Authentication

The server resolves the API key in this order:

1. `PENNYLANE_API_KEY` environment variable
2. `--apiKey <key>` CLI flag

Generate a Company API token at <https://pennylane.readme.io/docs/generating-my-api-token>.

## Use with Claude Desktop

Edit your Claude Desktop config:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pennylane": {
      "command": "npx",
      "args": ["-y", "@wanadev/pennylane-mcp"],
      "env": {
        "PENNYLANE_API_KEY": "your-token-here"
      }
    }
  }
}
```

Restart Claude Desktop and the Pennylane tools will appear under the hammer icon.

## Tool naming

Each operation in the OpenAPI spec becomes a tool named `pennylane_<operationId_in_snake_case>`. Examples:

| Tool                                | Endpoint                                   |
| ----------------------------------- | ------------------------------------------ |
| `pennylane_get_me`                  | `GET /me`                                  |
| `pennylane_get_customers`           | `GET /customers`                           |
| `pennylane_get_customer`            | `GET /customers/{id}`                      |
| `pennylane_post_company_customer`   | `POST /company_customers`                  |
| `pennylane_get_customer_invoices`   | `GET /customer_invoices`                   |
| `pennylane_finalize_customer_invoice` | `POST /customer_invoices/{id}/finalize`  |
| `pennylane_get_supplier_invoices`   | `GET /supplier_invoices`                   |
| `pennylane_get_products`            | `GET /products`                            |
| `pennylane_get_trial_balance`       | `GET /trial_balance`                       |

List endpoints accept `cursor` and `limit` for [cursor-based pagination](https://pennylane.readme.io/docs/using-cursor-based-pagination).

## Development

```bash
npm run sync:openapi   # re-fetch openapi/accounting.json from pennylane.readme.io
npm run generate       # regenerate src/generated/tools.ts from the OpenAPI
npm run build          # compile TypeScript → build/
npm run dev            # run the server with tsx (no compile step)
```

`src/generated/tools.ts` is git-ignored — it's a build artifact regenerated by the `prepare` script.

### Architecture

```
src/
├── server.ts          MCP server entry-point (CLI, stdio transport, signals)
├── client.ts          Axios-based Pennylane client (Bearer auth, error wrapping)
├── auth.ts            Resolves API key from env / CLI flag
└── generated/
    └── tools.ts       183 registerTool() calls, generated from OpenAPI

scripts/
├── sync-openapi.ts    Re-fetch the OpenAPI spec
└── generate-tools.ts  OpenAPI → src/generated/tools.ts

openapi/
└── accounting.json    Vendored OpenAPI 3.0 spec (~2 MB, 131 paths, 183 ops)
```

## Limits

- **Rate limits**: Pennylane caps requests at 4/s globally and 2/s on `customer_invoices`. The server does not throttle; rapid loops may hit `429 Too Many Requests`.
- **File downloads**: endpoints returning binary data (e.g. invoice PDFs) currently return the raw response as a JSON-stringified blob. A proper MCP `resource` mapping is a follow-up.
- **OAuth2**: only static API keys are supported. OAuth2 flows are a follow-up.

## License

MIT