Skip to main content
Glama
Simplicate MCP Server

Simplicate MCP Server

by daanno

Simplicate MCP Server

A Model Context Protocol (MCP) server that integrates with Simplicate, enabling AI assistants like Claude to securely access and interact with your Simplicate business data including CRM, projects, timesheets, and invoices.

Overview

This MCP server exposes Simplicate's API through the Model Context Protocol, allowing AI tools to:

  • Retrieve projects, organizations, persons, hours, and invoices

  • Search across Simplicate resources

  • Access detailed information about specific entities

Prerequisites

  • Node.js 18+ and npm

  • A Simplicate account with API credentials

  • Claude Desktop app (for testing with Claude)

Installation

  1. Clone or download this repository

  2. Install dependencies:

npm install
  1. Create a .env file based on .env.example:

cp .env.example .env
  1. Edit .env and add your Simplicate API credentials:

SIMPLICATE_API_KEY=your_api_key_here
SIMPLICATE_API_SECRET=your_api_secret_here
SIMPLICATE_API_BASE_URL=https://yourdomain.simplicate.com/api/v2

Getting Simplicate API Credentials:

  • Log in to your Simplicate account

  • Navigate to Settings → API

  • Generate or retrieve your API key and secret

  • Update the SIMPLICATE_API_BASE_URL with your actual Simplicate domain

Usage

Running the Server

Development mode (with TypeScript):

npm run dev

Production mode (compile first):

npm run build
npm start

HTTP MCP adapter (remote)

Start the HTTP MCP server (exposes /health, /tools, /call):

npm run build
PORT=3002 npm run start:http-mcp

This is the recommended way to expose tools on a remote host (Render, Docker, etc.).

Local Claude Desktop / stdio proxy

To forward a local StdIO-based MCP client (like Claude Desktop) to the remote HTTP MCP server, run:

REMOTE_MCP_URL=https://<your-remote>/call node src/stdio-proxy.js

The proxy reads newline-delimited JSON messages from stdin, forwards them as HTTP POST to REMOTE_MCP_URL, and writes the response back to stdout.

Render environment checklist

Set the following environment variables in Render (or other hosts):

  • SIMPLICATE_API_KEY

  • SIMPLICATE_API_SECRET

  • SIMPLICATE_API_BASE_URL

  • (optional) REMOTE_MCP_URL — used by the stdio-proxy

Connecting to Claude Desktop

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "simplicate": {
      "command": "node",
      "args": ["/absolute/path/to/Simplicate/dist/index.js"],
      "env": {
        "SIMPLICATE_API_KEY": "your_api_key_here",
        "SIMPLICATE_API_SECRET": "your_api_secret_here",
        "SIMPLICATE_API_BASE_URL": "https://yourdomain.simplicate.com/api/v2"
      }
    }
  }
}

Alternatively, using ts-node for development:

{
  "mcpServers": {
    "simplicate": {
      "command": "npx",
      "args": ["ts-node", "/absolute/path/to/Simplicate/src/index.ts"],
      "env": {
        "SIMPLICATE_API_KEY": "your_api_key_here",
        "SIMPLICATE_API_SECRET": "your_api_secret_here",
        "SIMPLICATE_API_BASE_URL": "https://yourdomain.simplicate.com/api/v2"
      }
    }
  }
}

After updating the configuration, restart Claude Desktop.

Available Tools

The MCP server exposes the following tools to AI assistants:

Projects

  • get_projects - Retrieve a list of projects

  • get_project - Get details of a specific project by ID

Organizations (CRM)

  • get_organizations - Retrieve a list of organizations

  • get_organization - Get details of a specific organization by ID

Persons (Contacts)

  • get_persons - Retrieve a list of persons

  • get_person - Get details of a specific person by ID

Hours (Timesheets)

  • get_hours - Retrieve timesheet hours

Invoices

  • get_invoices - Retrieve invoices

  • search - Search across Simplicate resources (projects, organizations, persons)

Available Resources

The server also exposes the following resources that can be read by AI assistants:

  • simplicate://projects - All projects

  • simplicate://organizations - All organizations

  • simplicate://persons - All persons

  • simplicate://hours - Timesheet hours

  • simplicate://invoices - All invoices

Project Structure

├── src/
│   ├── config/
│   │   └── config.ts           # Configuration management
│   ├── simplicate/
│   │   ├── client.ts           # Simplicate API client
│   │   └── services.ts         # Service layer for Simplicate API
│   ├── mcp/
│   │   └── server.ts           # MCP server implementation
│   └── index.ts                # Entry point
├── .env                        # Environment variables (not in git)
├── .env.example                # Example environment variables
├── package.json
├── tsconfig.json
└── README.md

Security Notes

  • Never commit your .env file or expose your API credentials

  • The .env file is included in .gitignore by default

  • Use environment variables for production deployments

  • Simplicate API credentials are transmitted securely via HTTPS

Development

Building

npm run build

Watch mode (auto-rebuild on changes)

npm run watch

Troubleshooting

Authentication Errors

  • Verify your API key and secret are correct

  • Ensure your Simplicate API base URL is correct (including your domain)

  • Check that your API credentials have the necessary permissions

Connection Issues

  • Ensure the MCP server is running

  • Check Claude Desktop config file syntax (valid JSON)

  • Verify the absolute path to the server entry point

  • Restart Claude Desktop after config changes

API Rate Limits

  • Simplicate may have API rate limits; adjust pagination parameters if needed

  • Consider caching frequently accessed data

Contributing

Contributions are welcome! Please ensure:

  • Code follows TypeScript best practices

  • All new features include appropriate error handling

Automatic deploys to Render (GitHub Actions)

This repository includes a GitHub Actions workflow at .github/workflows/deploy-to-render.yml which runs on push to main. The workflow builds the project and triggers a deploy via the Render API.

Required GitHub repository secrets:

  • RENDER_SERVICE_ID — the ID of your Render service (find in your Render dashboard)

  • RENDER_API_KEY — a Render API key with permission to create deploys

How it works:

  • On push to main, Actions checks out the code, installs dependencies (npm ci) and runs npm run build.

  • If the build succeeds, the workflow calls the Render API to trigger a deploy for the specified RENDER_SERVICE_ID.

Note: Render will still run your specified build/start commands as configured in the Render service settings.

  • Documentation is updated for new features

License

MIT

Resources

Support

For issues related to:

Available Tools

59 tools
create_absenceD

Create absence record

Inputs: absence_type (required), end_date (required), start_date (required), employee_id.

create_contractD

Create a new contract

Inputs: organization_id (required), start_date (required), end_date.

create_costD

Create a cost entry

Inputs: amount (required), description (required), date, project_id.

create_hoursC

Create a new hours entry

Inputs: hours (required), start_date (required), employee_id, note, +1 more.

create_invoiceD

Create a new invoice

Inputs: organization_id (required), date.

create_leaveC

Create leave/vacation entry

Inputs: end_date (required), leave_type (required), start_date (required), employee_id, +1 more.

create_mileageC

Create mileage entry

Inputs: date (required), distance (required), employee_id, project_id.

create_organizationC

Create a new organization

Inputs: name (required), email, phone, website.

create_paymentD

Create a payment record

Inputs: amount (required), invoice_id (required), method, payment_date.

create_personC

Create a new contact person

Inputs: family_name (required), first_name (required), email, organization_id.

create_projectC

Create a new project

Inputs: name (required), budget, organization_id, project_manager_id, +1 more.

create_quoteC

Create a new sales quote

Inputs: subject (required), organization_id.

create_serviceC

Create a new service

Inputs: name (required), price (required).

create_taskD

Create a new task

Inputs: title (required), assignee_id, due_date, project_id.

delete_hoursC

Delete hours entry

Inputs: hours_id (required).

delete_projectC

Delete a project

Inputs: project_id (required).

get_absencesC

Retrieve employee absences

Inputs: limit, offset.

get_calendar_eventsC

Get calendar/planning events

Inputs: limit, offset.

get_contractC

Get specific contract by ID

Inputs: contract_id (required).

get_contractsD

Retrieve contracts

Inputs: limit, offset.

get_costC

Get specific cost by ID

Inputs: cost_id (required).

get_costsC

Retrieve project costs

Inputs: limit, offset.

get_custom_fieldsC

Retrieve custom field definitions

Inputs: model.

get_default_servicesB

Get default services configuration

Inputs: no named parameters.

get_documentC

Get specific document by ID

Inputs: document_id (required).

get_documentsC

Retrieve documents

Inputs: limit, offset.

get_employeeC

Get specific employee by ID

Inputs: employee_id (required).

get_employeesC

Retrieve employees

Inputs: limit, offset.

get_hoursC

Retrieve timesheet hours

Inputs: limit, offset.

get_hours_entryC

Get specific hours entry by ID

Inputs: hours_id (required).

get_invoiceC

Get specific invoice by ID

Inputs: invoice_id (required).

get_invoicesD

Retrieve invoices

Inputs: limit, offset.

get_leaveC

Retrieve leave/vacation entries

Inputs: limit, offset.

get_mileageC

Retrieve mileage records

Inputs: limit, offset.

get_organizationC

Get specific organization by ID

Inputs: organization_id (required).

get_organizationsC

Retrieve CRM organizations

Inputs: limit, offset.

get_paymentsC

Retrieve invoice payments

Inputs: limit, offset.

get_personC

Get specific person by ID

Inputs: person_id (required).

get_personsC

Retrieve contact persons

Inputs: limit, offset.

get_projectC

Get details of a specific project by ID

Inputs: project_id (required).

get_projectsB

Retrieve a list of all projects

Inputs: limit, offset.

get_project_servicesC

Get services/items for a specific project

Inputs: project_id (required).

get_quoteC

Get specific quote by ID

Inputs: quote_id (required).

get_quotesC

Retrieve sales quotes

Inputs: limit, offset.

get_revenueC

Retrieve revenue records

Inputs: limit, offset.

get_saleC

Get specific sale by ID

Inputs: sale_id (required).

get_salesC

Retrieve sales records

Inputs: limit, offset.

get_serviceC

Get specific service by ID

Inputs: service_id (required).

get_servicesC

Retrieve services catalog

Inputs: limit, offset.

get_taskC

Get specific task by ID

Inputs: task_id (required).

get_tasksC

Retrieve project tasks

Inputs: limit, offset.

get_timesheetsD

Retrieve timesheets

Inputs: limit, offset.

update_hoursC

Update hours entry

Inputs: data (required), hours_id (required).

update_invoiceD

Update an invoice

Inputs: data (required), invoice_id (required).

update_organizationD

Update an organization

Inputs: data (required), organization_id (required).

update_personD

Update a person

Inputs: data (required), person_id (required).

update_projectC

Update an existing project

Inputs: data (required), project_id (required).

update_taskD

Update a task

Inputs: data (required), task_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 59 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. Tools are organized by resource type (e.g., absence, contract, hours) and action (create, get, update, delete), making it easy to distinguish between them. The naming convention clearly indicates which resource and operation each tool handles.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, with verbs like create, get, update, delete, and search paired with specific nouns. All tools use snake_case consistently, and there are no deviations in naming style or structure across the entire set.

    Tool Count2/5

    With 59 tools, the count is excessive for typical MCP server purposes, making it heavy and potentially overwhelming for agents. While the server covers a broad domain (CRM, project management, invoicing), the large number of tools suggests over-fragmentation rather than a well-scoped, streamlined interface.

    Completeness5/5

    The tool surface provides complete CRUD/lifecycle coverage for the Simplicate domain, including resources like absences, contracts, hours, invoices, organizations, persons, projects, quotes, services, and tasks. There are no obvious gaps, with create, get, update, and delete operations available for most core entities, plus auxiliary tools like search and custom fields.

    Related MCP Connectors