Tillit Local MCP Server

A local Model Context Protocol (MCP) server for the Tillit API, built with @modelcontextprotocol/sdk. This server provides 604+ tools and 134+ resources for complete access to the Tillit manufacturing operations platform.

Quick Start

Using npx (Recommended)

TENANT=your-tenant ENV_NAME=development API_KEY=your-key SECRET=your-secret npx @gotillit/local-mcp-server

Using .env file (Recommended for Development)

Copy the example file and customize it:

cp .env.example .env

Then edit .env with your actual values:

TENANT=bottling
ENV_NAME=development
API_KEY=your-api-key
SECRET=your-secret

Then run:

npx @gotillit/local-mcp-server

Manual Installation

npm install -g @gotillit/local-mcp-server
TENANT=your-tenant ENV_NAME=development API_KEY=your-key SECRET=your-secret tillit-mcp-server

Environment Variables

Required

• TENANT - Your tenant name (e.g., "bottling", "manufacturing")
• ENV_NAME - Environment name (e.g., "development", "staging", "production")
• API_KEY - Your API key for basic authentication
• SECRET - Your API secret for basic authentication

Optional

• LOG_LEVEL - Logging level (optional)

URL Construction

The server automatically constructs the API Gateway URL using the format:

https://{TENANT}.tillit-{ENV_NAME}.cloud

Examples:

• TENANT=bottling + ENV_NAME=development → https://bottling.tillit-development.cloud
• TENANT=manufacturing + ENV_NAME=production → https://manufacturing.tillit-production.cloud

Claude Desktop Integration

Add this configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "tillit": {
      "command": "npx",
      "args": ["@gotillit/local-mcp-server"],
      "env": {
        "TENANT": "bottling",
        "ENV_NAME": "development",
        "API_KEY": "your-api-key",
        "SECRET": "your-secret"
      }
    }
  }
}

Alternatively, if you have a .env file in the package directory, you can use a simpler configuration:

{
  "mcpServers": {
    "tillit": {
      "command": "npx",
      "args": ["@gotillit/local-mcp-server"]
    }
  }
}

Features

604+ API Tools

The server automatically provides tools for all Tillit API operations:

• Asset Management: Create, read, update, delete assets
• Order Management: Start, complete, suspend orders
• Activity Management: Template operations, instances, reporting
• User Management: CRUD operations, groups, permissions
• Analytics & Reporting: Cube queries, production reports
• Edge Device Management: Configuration, monitoring
• System Operations: Search, webhooks, translations

134+ Resources

Access structured information about different API categories:

• tillit://core - Core operations and data
• tillit://tenant - Tenant management
• tillit://activity - Activity operations
• tillit://cube - Analytics and reporting
• tillit://edge - Edge device management
• And 129+ more categories...

Authentication

The server uses Basic Authentication with your API key and secret:

Basic Authentication

The server automatically creates a Basic Auth header using your API_KEY and SECRET:

TENANT=bottling ENV_NAME=development API_KEY=your-key SECRET=your-secret npx @gotillit/local-mcp-server

This creates an Authorization header:

Authorization: Basic base64(API_KEY:SECRET)

Tenant Context

The TENANT environment variable is automatically added as a header:

tillit-tenant: bottling

Example Usage

Once connected to an MCP client (like Claude Desktop), you can:

List Available Tools

The client will automatically discover all 604+ available tools.

Execute API Operations

Use the "getAllAssets" tool to get all assets for site "production-line-1"

Access Resources

Read the "tillit://core" resource to see all core API operations

Search and Filter

Use the "search" tool to find assets containing "motor" in their name

Troubleshooting

Server Won't Start

• Verify TENANT and ENV_NAME are set correctly
• Check Node.js version (requires Node 18+)
• Ensure network connectivity to your Tillit API
• Verify the constructed URL (e.g., https://bottling.tillit-development.cloud) is accessible

Authentication Errors

• Verify API_KEY and SECRET are correct
• Check that your credentials have the required permissions
• Ensure the tenant name matches your account setup

Tool Execution Failures

• Check that your API credentials have the required permissions for the specific operations
• Verify the target API endpoint is accessible
• Review the tool parameters match the API requirements
• Check the server logs for detailed error messages

Environment Variable Issues

• If using a .env file, ensure it's in the same directory as the server
• Environment variables from the shell take precedence over .env file values
• Check for typos in variable names (case-sensitive)

Development

Local Development Setup

git clone <repository-url>
cd tillit-api/tillit-mcp/local
npm install
npm run build
node index.js

Building from Source

The build process copies the latest MCP tools and resources from the parent directory:

npm run build

This copies:

• ../mcp-tools.json → ./mcp-tools.json
• ../mcp-resources.json → ./mcp-resources.json

Technical Details

• Runtime: Node.js 18+
• Protocol: MCP over stdio transport
• Dependencies: @modelcontextprotocol/sdk, axios
• Architecture: Single-file executable with embedded JSON configuration

Support

For issues, questions, or feature requests, please contact the Tillit team or refer to the main project documentation.

License

UNLICENSED - Internal Tillit tool