Pennylane MCP Server - Functional Documentation

This document describes how to use the Pennylane MCP server and its capabilities. If you want informations about the technical implementation - see Technical documentation

Overview

The Pennylane MCP server allows AI assistants like Claude to connect to your Pennylane account and perform accounting-related tasks by leveraging the Pennylane API (V2).

Prerequisites

• Node.js (which includes npx) installed on your system.
• A valid Pennylane API key.

Obtaining a Pennylane API Key

(Instructions to be added here on how to get a Pennylane API key - typically from the user's Pennylane account settings or developer portal.)

Running the Server

Once you have your Pennylane API key, you can run the server using npx.

1. Via npx (once published to npm):

   npx pennylane-mcp --apiKey YOUR_PENNYLANE_API_KEY

2. For local development/testing (after cloning and building the repository):

   # From the root of the pennylane-mcp-server project
   npm run build
   node build/src/server.js --apiKey YOUR_PENNYLANE_API_KEY

   Replace YOUR_PENNYLANE_API_KEY with your actual Pennylane API key.

Connecting with Claude Desktop

1. Ensure the Pennylane MCP server is running using one of the methods above.

2. Open your Claude Desktop App configuration file:

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

3. Add or update the mcpServers section to include the Pennylane server. If you are running the server locally after building:

   {
     "mcpServers": {
       "pennylane": {
         "command": "node",
         "args": [
           "/ABSOLUTE/PATH/TO/YOUR/pennylane-mcp-server/build/src/server.js",
           "--apiKey",
           "YOUR_PENNYLANE_API_KEY"
         ]
       }
       // ... any other servers
     }
   }

   Replace /ABSOLUTE/PATH/TO/YOUR/pennylane-mcp-server/build/src/server.js with the actual absolute path to the compiled server file on your system, and YOUR_PENNYLANE_API_KEY with your API key.

   If the server is published and you are using npx:

   {
     "mcpServers": {
       "pennylane": {
         "command": "npx",
         "args": [
           "pennylane-mcp",
           "--apiKey",
           "YOUR_PENNYLANE_API_KEY"
         ]
       }
       // ... any other servers
     }
   }

4. Save the configuration file and restart Claude Desktop.

5. You should see the Pennylane tools available in Claude (hammer icon).

Available Tools (V1)

(This section will be populated as tools are implemented. Each tool will list its name, description, parameters, and an example of how to ask Claude to use it.)

Accounting

• List Journals (list_journals)

  • Description: Retrieves a list of all accounting journals.
  • Parameters: None
  • Example Claude Prompt: "Can you list all the accounting journals in Pennylane?"

• List Ledger Accounts (list_ledger_accounts)

  • Description: Retrieves a list of ledger accounts.
  • Parameters: (To be defined based on API - e.g., filters)
  • Example Claude Prompt: "Show me the list of ledger accounts."

• List Ledger Entries (list_ledger_entries)

  • Description: Retrieves a list of ledger entries.
  • Parameters: (To be defined based on API - e.g., date range, journal ID)
  • Example Claude Prompt: "List the recent ledger entries."

• Create Ledger Entry (create_ledger_entry)

  • Description: Creates a new ledger entry.
  • Parameters: (Details of the ledger entry - e.g., date, journal, lines with account, debit, credit, label)
  • Example Claude Prompt: "Create a new ledger entry for a purchase of office supplies."

• Get Trial Balance (get_trial_balance)

  • Description: Retrieves the trial balance.
  • Parameters: (To be defined based on API - e.g., date range)
  • Example Claude Prompt: "What is the current trial balance?"

Customers & Customer Invoices

• List Customers (list_customers)

  • Description: Retrieves a list of customers.
  • Parameters: (To be defined based on API)
  • Example Claude Prompt: "Show me all customers."

• Create Customer (create_customer)

  • Description: Creates a new customer (company or individual).
  • Parameters: (Customer details - name, type, email, address, etc.)
  • Example Claude Prompt: "Add a new customer named 'Global Corp Inc.'"

• Retrieve Customer (get_customer)

  • Description: Retrieves details for a specific customer.
  • Parameters: customerId (string)
  • Example Claude Prompt: "Get the details for customer ID 12345."

• List Customer Invoices (list_customer_invoices)

  • Description: Retrieves a list of customer invoices.
  • Parameters: (To be defined based on API - e.g., customer ID, status, date range)
  • Example Claude Prompt: "List all open customer invoices."

• Create Customer Invoice (create_customer_invoice)

  • Description: Creates a new customer invoice.
  • Parameters: (Invoice details - customer ID, lines, dates, amounts, etc.)
  • Example Claude Prompt: "Create an invoice for 'Global Corp Inc.' for the recent consultation services."

• Retrieve Customer Invoice (get_customer_invoice)

  • Description: Retrieves details for a specific customer invoice.
  • Parameters: invoiceId (string)
  • Example Claude Prompt: "Show me invoice INV-007."

Suppliers & Supplier Invoices

• List Suppliers (list_suppliers)

  • Description: Retrieves a list of suppliers.
  • Parameters: (To be defined based on API)
  • Example Claude Prompt: "List all our suppliers."

• Create Supplier (create_supplier)

  • Description: Creates a new supplier.
  • Parameters: (Supplier details - name, contact info, etc.)
  • Example Claude Prompt: "Add 'Office Supplies Co.' as a new supplier."

• List Supplier Invoices (list_supplier_invoices)

  • Description: Retrieves a list of supplier invoices.
  • Parameters: (To be defined based on API - e.g., supplier ID, status, date range)
  • Example Claude Prompt: "Show me all unpaid supplier invoices."

• Retrieve Supplier Invoice (get_supplier_invoice)

  • Description: Retrieves details for a specific supplier invoice.
  • Parameters: invoiceId (string)
  • Example Claude Prompt: "Get details for supplier invoice 67890."

Transactions

• List Bank Accounts (list_bank_accounts)

  • Description: Retrieves a list of bank accounts connected to Pennylane.
  • Parameters: None
  • Example Claude Prompt: "List all bank accounts in Pennylane."

• List Transactions (list_transactions)

  • Description: Retrieves a list of bank transactions.
  • Parameters: (To be defined based on API - e.g., bank account ID, date range)
  • Example Claude Prompt: "Show recent bank transactions."

• Retrieve Transaction (get_transaction)

  • Description: Retrieves details for a specific bank transaction.
  • Parameters: transactionId (string)
  • Example Claude Prompt: "Get details for transaction ID ABC123XYZ."

Troubleshooting

• Error: API Key Invalid/Missing: Ensure you have provided the correct API key via the --apiKey argument and that it has the necessary permissions in Pennylane.
• Server Not Starting: Check the console output for any error messages when you try to run the server. Ensure Node.js is installed correctly.
• Tools Not Appearing in Claude:
  • Verify the claude_desktop_config.json path and command are correct.
  • Ensure the server is running before starting or restarting Claude Desktop.
  • Check Claude Desktop's MCP logs: ~/Library/Logs/Claude/mcp.log (macOS) or %APPDATA%\Claude\logs\mcp.log (Windows) and specific server logs like mcp-server-pennylane.log.

Further troubleshooting steps will be added as common issues are identified.