MCP ERPNext

MCP ERPNext

 

Model Context Protocol (MCP) server for ERPNext - manage timesheets, leave applications, projects, and software releases via Claude, Gemini, or any MCP-compatible AI assistant.

Features

• Timesheets: Create, edit, submit, and manage timesheets
• Leave Applications: Apply for leave, check balances, manage applications
• Projects: List projects and tasks
• Software Releases: Create release documents from GitLab merge requests with auto-detection
• Smart Validation: Automatic overlap detection for time entries
• Draft Editing: Full support for editing draft timesheets

Installation

Via npm (recommended)

npm install -g mcp-erpnext

From source

git clone https://github.com/sharat9703/mcp-erpnext-taiga-gitlab-redmine.git
cd mcp-erpnext
npm install

Configuration

1. Set up credentials

Create a .env file or set environment variables:

ERPNEXT_URL=https://your-erpnext-instance.com
ERPNEXT_USERNAME=your-email@example.com
ERPNEXT_PASSWORD=your-password
ERPNEXT_TOTP_SECRET=your-totp-secret  # Optional, for 2FA

# For Software Releases (optional)
GITLAB_URL=https://gitlab.example.com
GITLAB_TOKEN=your-gitlab-personal-access-token
REDMINE_URL=https://redmine.example.com
REDMINE_API_KEY=your-redmine-api-key  # For auto-fetching ticket titles

2. Configure your AI client

Claude Desktop (~/.claude/claude_desktop_config.json or %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "erpnext": {
      "command": "npx",
      "args": ["mcp-erpnext"],
      "env": {
        "ERPNEXT_URL": "https://your-erpnext-instance.com",
        "ERPNEXT_USERNAME": "your-username",
        "ERPNEXT_PASSWORD": "your-password"
      }
    }
  }
}

Or from local installation:

{
  "mcpServers": {
    "erpnext": {
      "command": "node",
      "args": ["/path/to/mcp-erpnext/src/index.js"]
    }
  }
}

Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "erpnext": {
      "command": "npx",
      "args": ["mcp-erpnext"],
      "env": {
        "ERPNEXT_URL": "https://your-erpnext-instance.com",
        "ERPNEXT_USERNAME": "your-username",
        "ERPNEXT_PASSWORD": "your-password"
      }
    }
  }
}

Usage Examples

Once configured, you can ask your AI assistant:

Create weekly timesheet for project PROJ-0460

Show my draft timesheets

Submit timesheet TS-2025-00123

Apply for leave from Dec 25 to Dec 27

Update time log 0 in timesheet TS-2025-00123 to 8 hours

Create software release for https://gitlab.example.com/project/-/merge_requests/123
using template https://erp.example.com/app/software-release/Product-v1.0.0

See USAGE.md for complete examples.

Available Tools

Timesheets

| Tool | Description | |------|-------------| | erpnext_create_weekly_timesheet | Create weekly timesheet (7h billable + 2h non-billable/day) | | erpnext_create_timesheet | Create custom timesheet | | erpnext_create_custom_timesheet | Create timesheet with specific entries | | erpnext_list_timesheets | List timesheets with filters | | erpnext_get_timesheet | Get timesheet details | | erpnext_get_my_draft_timesheets | Get current user's draft timesheets | | erpnext_update_time_log | Edit a time entry in draft timesheet | | erpnext_remove_time_log | Remove a time entry from draft | | erpnext_update_timesheet_note | Update timesheet note | | erpnext_delete_timesheet | Delete draft timesheet | | erpnext_submit_timesheet | Submit for approval | | erpnext_cancel_timesheet | Cancel timesheet |

Leave Applications

| Tool | Description | |------|-------------| | erpnext_apply_leave | Apply for leave | | erpnext_list_leave_applications | List leave applications | | erpnext_get_my_pending_leaves | Get pending leave applications | | erpnext_get_leave_balance | Check leave balance | | erpnext_submit_leave_application | Submit for approval | | erpnext_cancel_leave_application | Cancel leave application |

Core

| Tool | Description | |------|-------------| | erpnext_login | Authenticate with ERPNext | | erpnext_get_current_employee | Get logged-in user's employee record | | erpnext_list_projects | List projects | | erpnext_list_tasks | List tasks for a project | | erpnext_list_activity_types | List available activity types |

Software Releases

| Tool | Description | |------|-------------| | erpnext_preview_software_release | Preview release before creating - shows all fields and sources | | erpnext_create_software_release | Create release from GitLab MR with auto-detection | | erpnext_get_mr_details | Get MR details (Redmine IDs, patches, version) | | erpnext_get_redmine_issue | Get Redmine ticket title | | erpnext_get_software_release | Get existing release (use as template) | | erpnext_list_software_releases | List recent releases | | erpnext_list_products | List available products | | erpnext_list_customers_for_release | List available customers |

Key Features

Time Entry Overlap Prevention

The server automatically validates that time entries don't overlap:

Error: Time entries have overlapping times:
Time entry 1 (Billable Work: 2025-12-02 10:00:00 - 17:00:00) overlaps with
entry 2 (Non Billable Work: 2025-12-02 15:00:00 - 17:00:00)

Draft Editing

Edit draft timesheets before submission:

• Update hours, times, project, activity type
• Remove individual time entries
• Update notes
• Delete entire draft

Software Release Auto-Detection

Create software releases from GitLab MRs with intelligent auto-detection:

• Template-based: Use existing release as template (auto-fills Product, Customer, Reviewer)
• Redmine IDs: Auto-extracted from MR description tables (| 1. | #124323 | Title |)
• Redmine Titles: Auto-fetched from Redmine API if configured
• Version: Auto-detected from branch name (e.g., release-v1.0.0.12)
• Customer: Auto-detected from GitLab project path
• Patch URLs: Auto-extracted from MR notes/attachments
• Test Reports: Auto-extracted from MR notes/attachments

Project Structure

mcp-erpnext/
├── src/
│   ├── index.js              # Entry point
│   ├── erpnext-client.js     # ERPNext API client
│   ├── gitlab-client.js      # GitLab API client (for software releases)
│   ├── redmine-client.js     # Redmine API client (for ticket titles)
│   ├── resources.js          # MCP resources
│   ├── definitions/          # Tool schemas
│   ├── handlers/             # Tool handlers
│   ├── tools/                # Business logic
│   └── formatters/           # Response formatters
├── .env.example
├── package.json
├── README.md
└── USAGE.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Author

Sharat Yaragatti - GitHub