ERPNext MCP Server

Instructions

Implementation Reference

• src/index.ts:447-487 (handler)

  Tool handler for 'get_documents': validates authentication and parameters, calls erpnext.getDocList to fetch documents, and returns JSON stringified result or error.

  case "get_documents": {
    if (!erpnext.isAuthenticated()) {
      return {
        content: [{
          type: "text",
          text: "Not authenticated with ERPNext. Please configure API key authentication."
        }],
        isError: true
      };
    }
    
    const doctype = String(request.params.arguments?.doctype);
    const fields = request.params.arguments?.fields as string[] | undefined;
    const filters = request.params.arguments?.filters as Record<string, any> | undefined;
    const limit = request.params.arguments?.limit as number | undefined;
    
    if (!doctype) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Doctype is required"
      );
    }
    
    try {
      const documents = await erpnext.getDocList(doctype, filters, fields, limit);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(documents, null, 2)
        }]
      };
    } catch (error: any) {
      return {
        content: [{
          type: "text",
          text: `Failed to get ${doctype} documents: ${error?.message || 'Unknown error'}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:348-376 (schema)

  Input schema definition for the 'get_documents' tool, specifying required 'doctype' and optional fields, filters, limit.

    name: "get_documents",
    description: "Get a list of documents for a specific doctype",
    inputSchema: {
      type: "object",
      properties: {
        doctype: {
          type: "string",
          description: "ERPNext DocType (e.g., Customer, Item)"
        },
        fields: {
          type: "array",
          items: {
            type: "string"
          },
          description: "Fields to include (optional)"
        },
        filters: {
          type: "object",
          additionalProperties: true,
          description: "Filters in the format {field: value} (optional)"
        },
        limit: {
          type: "number",
          description: "Maximum number of documents to return (optional)"
        }
      },
      required: ["doctype"]
    }
  },

• src/index.ts:324-439 (registration)

  Registration of 'get_documents' tool in the list of available tools returned by ListToolsRequestSchema handler.

    tools: [
      {
        name: "get_doctypes",
        description: "Get a list of all available DocTypes",
        inputSchema: {
          type: "object",
          properties: {}
        }
      },
      {
        name: "get_doctype_fields",
        description: "Get fields list for a specific DocType",
        inputSchema: {
          type: "object",
          properties: {
            doctype: {
              type: "string",
              description: "ERPNext DocType (e.g., Customer, Item)"
            }
          },
            required: ["doctype"]
        }
      },
      {
        name: "get_documents",
        description: "Get a list of documents for a specific doctype",
        inputSchema: {
          type: "object",
          properties: {
            doctype: {
              type: "string",
              description: "ERPNext DocType (e.g., Customer, Item)"
            },
            fields: {
              type: "array",
              items: {
                type: "string"
              },
              description: "Fields to include (optional)"
            },
            filters: {
              type: "object",
              additionalProperties: true,
              description: "Filters in the format {field: value} (optional)"
            },
            limit: {
              type: "number",
              description: "Maximum number of documents to return (optional)"
            }
          },
          required: ["doctype"]
        }
      },
      {
        name: "create_document",
        description: "Create a new document in ERPNext",
        inputSchema: {
          type: "object",
          properties: {
            doctype: {
              type: "string",
              description: "ERPNext DocType (e.g., Customer, Item)"
            },
            data: {
              type: "object",
              additionalProperties: true,
              description: "Document data"
            }
          },
          required: ["doctype", "data"]
        }
      },
      {
        name: "update_document",
        description: "Update an existing document in ERPNext",
        inputSchema: {
          type: "object",
          properties: {
            doctype: {
              type: "string",
              description: "ERPNext DocType (e.g., Customer, Item)"
            },
            name: {
              type: "string",
              description: "Document name/ID"
            },
            data: {
              type: "object",
              additionalProperties: true,
              description: "Document data to update"
            }
          },
          required: ["doctype", "name", "data"]
        }
      },
      {
        name: "run_report",
        description: "Run an ERPNext report",
        inputSchema: {
          type: "object",
          properties: {
            report_name: {
              type: "string",
              description: "Name of the report"
            },
            filters: {
              type: "object",
              additionalProperties: true,
              description: "Report filters (optional)"
            }
          },
          required: ["report_name"]
        }
      }
    ]
  };

• src/index.ts:80-101 (helper)

  ERPNextClient.getDocList method: performs the actual API request to fetch document list for a doctype with optional filters, fields, and limit.

  async getDocList(doctype: string, filters?: Record<string, any>, fields?: string[], limit?: number): Promise<any[]> {
    try {
      let params: Record<string, any> = {};
      
      if (fields && fields.length) {
        params['fields'] = JSON.stringify(fields);
      }
      
      if (filters) {
        params['filters'] = JSON.stringify(filters);
      }
      
      if (limit) {
        params['limit_page_length'] = limit;
      }
      
      const response = await this.axiosInstance.get(`/api/resource/${doctype}`, { params });
      return response.data.data;
    } catch (error: any) {
      throw new Error(`Failed to get ${doctype} list: ${error?.message || 'Unknown error'}`);
    }
  }