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:

3. Create a .env file based on .env.example:

4. Edit .env and add your Simplicate API credentials:

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):

Production mode (compile first):

HTTP MCP adapter (remote)

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

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:

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

Alternatively, using ts-node for development:

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 - 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

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

Watch mode (auto-rebuild on changes)

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

• Model Context Protocol Documentation

• Simplicate API Documentation

• Claude Desktop

Support

For issues related to:

• MCP Server: Open an issue in this repository

• Simplicate API: Contact Simplicate Support

• Claude/MCP Protocol: Visit Anthropic's Documentation