lunchmoney-mcp

Instructions

Implementation Reference

• src/index.ts:144-172 (registration)

  Registration of the 'get-recent-transactions' tool using McpServer.tool(), including description, input schema, and inline handler function.

  this.server.tool(
      "get-recent-transactions",
      "Get recent transactions",
      {
          days: z.number().default(30).describe("Number of days to look back"),
          limit: z.number().default(10).describe("Maximum number of transactions to return"),
      },
      async ({ days, limit }) => {
          const endDate = new Date().toISOString().split('T')[0];
          const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
              .toISOString()
              .split('T')[0];
  
          const transactions = await this.fetchTransactions({
              start_date: startDate,
              end_date: endDate,
              limit,
          });
  
          return {
              content: [
                  {
                      type: "text",
                      text: this.formatTransactions(transactions),
                  },
              ],
          };
      },
  );

• src/index.ts:151-170 (handler)

  The main handler function for the tool, which calculates date range, fetches transactions using helper, formats them, and returns as text content.

  async ({ days, limit }) => {
      const endDate = new Date().toISOString().split('T')[0];
      const startDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
          .toISOString()
          .split('T')[0];
  
      const transactions = await this.fetchTransactions({
          start_date: startDate,
          end_date: endDate,
          limit,
      });
  
      return {
          content: [
              {
                  type: "text",
                  text: this.formatTransactions(transactions),
              },
          ],
      };

• src/index.ts:147-150 (schema)

  Zod schema defining input parameters: days (default 30) and limit (default 10).

  {
      days: z.number().default(30).describe("Number of days to look back"),
      limit: z.number().default(10).describe("Maximum number of transactions to return"),
  },

• src/index.ts:315-335 (helper)

  Helper method to fetch transactions from Lunchmoney API using the provided parameters, handles query params, auth, and error checking.

  private async fetchTransactions(params: Record<string, any>): Promise<Transaction[]> {
      const queryParams = new URLSearchParams();
      for (const [key, value] of Object.entries(params)) {
          queryParams.append(key, value.toString());
      }
  
      const response = await fetch(`${API_BASE}/transactions?${queryParams}`, {
          headers: {
              Authorization: `Bearer ${this.token}`,
              Accept: "application/json",
          }
      });
  
      if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
      }
  
      const data = await response.json() as TransactionResponse;
      return data.transactions || [];
  }

• src/index.ts:336-359 (helper)

  Helper method to format a list of transactions into a readable text string with key details.

  private formatTransactions(transactions: Transaction[]): string {
      return transactions
          .map(tx => {
              let summary = [
                  `Date: ${tx.date}`,
                  `Amount: ${tx.amount} ${tx.currency.toUpperCase()}`,
                  `Payee: ${tx.payee}`,
                  `Category: ${tx.category_name} (${tx.category_group_name})`,
                  `Account: ${tx.account_display_name || "N/A"}`,
                  `Status: ${tx.status}`,
              ];
  
              if (tx.tags && tx.tags.length > 0) {
                  summary.push(`Tags: ${tx.tags.map((t: Tag) => t.name).join(", ")}`);
              }
  
              if (tx.notes) {
                  summary.push(`Notes: ${tx.notes}`);
              }
  
              return summary.join("\n");
          })
          .join("\n\n---\n\n");
  }