LunchMoney MCP Server

Instructions

Implementation Reference

• src/tools/recurring-items.ts:26-67 (handler)

  The handler function that fetches recurring items from the Lunchmoney API using the provided parameters.

  async ({ input }) => {
      const { baseUrl, lunchmoneyApiToken } = getConfig();
      
      const params = new URLSearchParams();
      if (input.start_date) params.append("start_date", input.start_date);
      if (input.end_date) params.append("end_date", input.end_date);
      if (input.debit_as_negative !== undefined) {
          params.append("debit_as_negative", input.debit_as_negative.toString());
      }
      
      const url = params.toString() 
          ? `${baseUrl}/recurring_items?${params}`
          : `${baseUrl}/recurring_items`;
          
      const response = await fetch(url, {
          headers: {
              Authorization: `Bearer ${lunchmoneyApiToken}`,
          },
      });
  
      if (!response.ok) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to get recurring items: ${response.statusText}`,
                  },
              ],
          };
      }
  
      const recurringItems: RecurringItem[] = await response.json();
      
      return {
          content: [
              {
                  type: "text",
                  text: JSON.stringify(recurringItems),
              },
          ],
      };
  }

• src/tools/recurring-items.ts:11-24 (schema)

  Zod schema defining the input parameters for the get_recurring_items tool.

  input: z.object({
      start_date: z
          .string()
          .optional()
          .describe("Start date in YYYY-MM-DD format. Defaults to first day of current month"),
      end_date: z
          .string()
          .optional()
          .describe("End date in YYYY-MM-DD format"),
      debit_as_negative: z
          .boolean()
          .optional()
          .describe("Pass true to return debit amounts as negative"),
  }),

• src/tools/recurring-items.ts:6-69 (registration)

  The registration function that calls server.tool() to register the get_recurring_items tool.

  export function registerRecurringItemsTools(server: McpServer) {
      server.tool(
          "get_recurring_items",
          "Retrieve a list of recurring items to expect for a specified month",
          {
              input: z.object({
                  start_date: z
                      .string()
                      .optional()
                      .describe("Start date in YYYY-MM-DD format. Defaults to first day of current month"),
                  end_date: z
                      .string()
                      .optional()
                      .describe("End date in YYYY-MM-DD format"),
                  debit_as_negative: z
                      .boolean()
                      .optional()
                      .describe("Pass true to return debit amounts as negative"),
              }),
          },
          async ({ input }) => {
              const { baseUrl, lunchmoneyApiToken } = getConfig();
              
              const params = new URLSearchParams();
              if (input.start_date) params.append("start_date", input.start_date);
              if (input.end_date) params.append("end_date", input.end_date);
              if (input.debit_as_negative !== undefined) {
                  params.append("debit_as_negative", input.debit_as_negative.toString());
              }
              
              const url = params.toString() 
                  ? `${baseUrl}/recurring_items?${params}`
                  : `${baseUrl}/recurring_items`;
                  
              const response = await fetch(url, {
                  headers: {
                      Authorization: `Bearer ${lunchmoneyApiToken}`,
                  },
              });
  
              if (!response.ok) {
                  return {
                      content: [
                          {
                              type: "text",
                              text: `Failed to get recurring items: ${response.statusText}`,
                          },
                      ],
                  };
              }
  
              const recurringItems: RecurringItem[] = await response.json();
              
              return {
                  content: [
                      {
                          type: "text",
                          text: JSON.stringify(recurringItems),
                      },
                  ],
              };
          }
      );
  }

• src/index.ts:27-27 (registration)

  Top-level call to register the recurring items tools on the MCP server.

  registerRecurringItemsTools(server);