LunchMoney MCP Server

Instructions

Implementation Reference

• src/tools/budgets.ts:30-69 (handler)

  Handler function that fetches the budget summary from the Lunch Money API for the given date range and currency, returns the budgets as JSON or error message.

  async ({ input }) => {
      const { baseUrl, lunchmoneyApiToken } = getConfig();
  
      const params = new URLSearchParams({
          start_date: input.start_date,
          end_date: input.end_date,
      });
  
      if (input.currency) {
          params.append("currency", input.currency);
      }
  
      const response = await fetch(`${baseUrl}/budgets?${params}`, {
          headers: {
              Authorization: `Bearer ${lunchmoneyApiToken}`,
          },
      });
  
      if (!response.ok) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to get budget summary: ${response.statusText}`,
                  },
              ],
          };
      }
  
      const budgets: Budget[] = await response.json();
  
      return {
          content: [
              {
                  type: "text",
                  text: JSON.stringify(budgets),
              },
          ],
      };
  }

• src/tools/budgets.ts:11-28 (schema)

  Input schema using Zod validating start_date, end_date (required, YYYY-MM-DD monthly bounds), and optional currency.

  input: z.object({
      start_date: z
          .string()
          .describe(
              "Start date in YYYY-MM-DD format. Lunch Money currently only supports monthly budgets, so your date should be the start of a month (eg. 2021-04-01)"
          ),
      end_date: z
          .string()
          .describe(
              "End date in YYYY-MM-DD format. Lunch Money currently only supports monthly budgets, so your date should be the end of a month (eg. 2021-04-30)"
          ),
      currency: z
          .string()
          .optional()
          .describe(
              "Currency for budget (defaults to primary currency)"
          ),
  }),

• src/tools/budgets.ts:8-70 (registration)

  Registration of the get_budget_summary tool on the McpServer, specifying name, description, input schema, and inline handler function.

      "get_budget_summary",
      "Get budget summary for a specific date range. The budgeted and spending amounts will be broken down by month.",
      {
          input: z.object({
              start_date: z
                  .string()
                  .describe(
                      "Start date in YYYY-MM-DD format. Lunch Money currently only supports monthly budgets, so your date should be the start of a month (eg. 2021-04-01)"
                  ),
              end_date: z
                  .string()
                  .describe(
                      "End date in YYYY-MM-DD format. Lunch Money currently only supports monthly budgets, so your date should be the end of a month (eg. 2021-04-30)"
                  ),
              currency: z
                  .string()
                  .optional()
                  .describe(
                      "Currency for budget (defaults to primary currency)"
                  ),
          }),
      },
      async ({ input }) => {
          const { baseUrl, lunchmoneyApiToken } = getConfig();
  
          const params = new URLSearchParams({
              start_date: input.start_date,
              end_date: input.end_date,
          });
  
          if (input.currency) {
              params.append("currency", input.currency);
          }
  
          const response = await fetch(`${baseUrl}/budgets?${params}`, {
              headers: {
                  Authorization: `Bearer ${lunchmoneyApiToken}`,
              },
          });
  
          if (!response.ok) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to get budget summary: ${response.statusText}`,
                      },
                  ],
              };
          }
  
          const budgets: Budget[] = await response.json();
  
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(budgets),
                  },
              ],
          };
      }
  );