LunchMoney MCP Server

Instructions

Implementation Reference

• src/tools/categories.ts:149-203 (handler)

  The handler function for the 'create_category' tool. It extracts input parameters, constructs a request body, makes a POST request to the Lunchmoney API /categories endpoint, handles errors, and returns the created category as JSON.

  async ({ input }) => {
      const {
          name,
          description,
          is_income,
          exclude_from_budget,
          exclude_from_totals,
          archived,
          group_id,
      } = input;
      const { baseUrl, lunchmoneyApiToken } = getConfig();
      const requestBody: any = {
          name,
          description,
          is_income,
          exclude_from_budget,
          exclude_from_totals,
          archived,
      };
  
      if (group_id !== undefined) {
          requestBody.group_id = group_id;
      }
  
      const response = await fetch(`${baseUrl}/categories`, {
          method: "POST",
          headers: {
              Authorization: `Bearer ${lunchmoneyApiToken}`,
              "Content-Type": "application/json",
          },
          body: JSON.stringify(requestBody),
      });
  
      if (!response.ok) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to create a single category: ${response.statusText}`,
                  },
              ],
          };
      }
  
      const category: Category = await response.json();
      
      return {
          content: [
              {
                  type: "text",
                  text: JSON.stringify(category),
              },
          ],
      };
  }

• src/tools/categories.ts:102-147 (schema)

  The Zod input schema for the 'create_category' tool, defining parameters like name, description, various boolean flags, and optional group_id.

  input: z.object({
      name: z
          .string()
          .describe(
              "Name of category. Must be between 1 and 40 characters."
          ),
      description: z
          .string()
          .optional()
          .default("")
          .describe(
              "Description of category. Must be less than 140 characters."
          ),
      is_income: z
          .boolean()
          .optional()
          .default(false)
          .describe(
              "Whether or not transactions in this category should be treated as income."
          ),
      exclude_from_budget: z
          .boolean()
          .optional()
          .default(false)
          .describe(
              "Whether or not transactions in this category should be excluded from budgets."
          ),
      exclude_from_totals: z
          .boolean()
          .optional()
          .default(false)
          .describe(
              "Whether or not transactions in this category should be excluded from calculated totals."
          ),
      archived: z
          .boolean()
          .optional()
          .default(false)
          .describe("Whether or not category should be archived."),
      group_id: z
          .number()
          .optional()
          .describe(
              "Assigns the newly-created category to an existing category group."
          ),
  }),

• src/tools/categories.ts:98-204 (registration)

  The registration of the 'create_category' tool via server.tool(), which includes the tool name, description, input schema, and handler function. This is called within the registerCategoryTools function.

  server.tool(
      "create_category",
      "Create a single category.",
      {
          input: z.object({
              name: z
                  .string()
                  .describe(
                      "Name of category. Must be between 1 and 40 characters."
                  ),
              description: z
                  .string()
                  .optional()
                  .default("")
                  .describe(
                      "Description of category. Must be less than 140 characters."
                  ),
              is_income: z
                  .boolean()
                  .optional()
                  .default(false)
                  .describe(
                      "Whether or not transactions in this category should be treated as income."
                  ),
              exclude_from_budget: z
                  .boolean()
                  .optional()
                  .default(false)
                  .describe(
                      "Whether or not transactions in this category should be excluded from budgets."
                  ),
              exclude_from_totals: z
                  .boolean()
                  .optional()
                  .default(false)
                  .describe(
                      "Whether or not transactions in this category should be excluded from calculated totals."
                  ),
              archived: z
                  .boolean()
                  .optional()
                  .default(false)
                  .describe("Whether or not category should be archived."),
              group_id: z
                  .number()
                  .optional()
                  .describe(
                      "Assigns the newly-created category to an existing category group."
                  ),
          }),
      },
      async ({ input }) => {
          const {
              name,
              description,
              is_income,
              exclude_from_budget,
              exclude_from_totals,
              archived,
              group_id,
          } = input;
          const { baseUrl, lunchmoneyApiToken } = getConfig();
          const requestBody: any = {
              name,
              description,
              is_income,
              exclude_from_budget,
              exclude_from_totals,
              archived,
          };
  
          if (group_id !== undefined) {
              requestBody.group_id = group_id;
          }
  
          const response = await fetch(`${baseUrl}/categories`, {
              method: "POST",
              headers: {
                  Authorization: `Bearer ${lunchmoneyApiToken}`,
                  "Content-Type": "application/json",
              },
              body: JSON.stringify(requestBody),
          });
  
          if (!response.ok) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to create a single category: ${response.statusText}`,
                      },
                  ],
              };
          }
  
          const category: Category = await response.json();
          
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(category),
                  },
              ],
          };
      }
  );

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

  Invocation of registerCategoryTools(server) in the main server setup, which registers the create_category tool among others.

  registerCategoryTools(server);