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

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

cp .env.example .env

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

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