@itcons-app/mcp

Itcons.app MCP Server

Model Context Protocol server for connecting AI assistants to Itcons.app.

Itcons.app is a business operations platform for managing work reports, work orders, projects, clients, users, and related operational resources. It is designed to help teams digitize field and office workflows around daily reports, assignments, task tracking, and service execution.

This server runs over stdio and lets MCP-compatible clients such as Codex, Claude Desktop, and other local MCP hosts use the Itcons.app API with the user's own installation domain and credentials.

With this MCP server, an assistant can query Itcons.app data, search work reports and work orders, list operational catalogs such as statuses, users, resources, projects, and clients, and create supported Itcons.app records when the configured user has permission to do so.

Features

• Authenticate with POST /api/login_check.
• Use Bearer authentication for Itcons.app API calls.
• Resolve the API base URL from ITCONS_DOMAIN.
• List statuses, users, resources, clients, projects, work order types, and work report models.
• Search work reports and work orders.
• Create clients, projects, users, and work orders.

Webhooks are intentionally not included in this stdio MCP server. Webhooks require a public HTTP endpoint, while this server is launched locally by the MCP client.

Installation

From npm:

npm install -g @itcons-app/mcp

From this repository:

npm install
npm run check

If Node was installed with Homebrew and node/npm are not in your PATH, use:

/opt/homebrew/opt/node/bin/npm install
/opt/homebrew/opt/node/bin/npm run check

Configuration

The server reads credentials from environment variables.

ITCONS_DOMAIN=demo
ITCONS_USERNAME=[e-mail]
ITCONS_PASSWORD=change-me
ITCONS_TIMEZONE=Europe/Madrid

For https://demo.itcons.app, set:

ITCONS_DOMAIN=demo

You may use an existing Bearer token instead of username/password:

ITCONS_DOMAIN=demo
ITCONS_TOKEN=ey...

ITCONS_API_BASE_URL is optional. If omitted, the server uses:

https://ITCONS_DOMAIN.itcons.app/api

MCP Client Example

Example configuration using a globally installed package:

{
  "mcpServers": {
    "itcons-app": {
      "command": "itcons-app-mcp",
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "[e-mail]",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

Example configuration using a local checkout:

{
  "mcpServers": {
    "itcons-app": {
      "command": "node",
      "args": [
        "/absolute/path/to/itcons-app-mcp/src/index.js"
      ],
      "env": {
        "ITCONS_DOMAIN": "demo",
        "ITCONS_USERNAME": "[e-mail]",
        "ITCONS_PASSWORD": "change-me",
        "ITCONS_TIMEZONE": "Europe/Madrid"
      }
    }
  }
}

Tools

Read-only tools:

• itcons_check_connection
• itcons_list_workorder_types
• itcons_list_work_report_models
• itcons_list_projects
• itcons_list_clients
• itcons_list_statuses
• itcons_list_users
• itcons_list_resources
• itcons_search_workorders
• itcons_list_pending_workorders
• itcons_search_work_reports
• itcons_list_work_reports_by_date
• itcons_list_today_work_reports

Create tools:

• itcons_create_workorder
• itcons_create_user
• itcons_create_project
• itcons_create_client

Environment Variables

Variable	Required	Description
ITCONS_DOMAIN	Yes	Installation subdomain. For https://demo.itcons.app, use demo.
ITCONS_USERNAME	Yes, unless ITCONS_TOKEN is set	Itcons.app username or email.
ITCONS_PASSWORD	Yes, unless ITCONS_TOKEN is set	Itcons.app password.
ITCONS_TOKEN	No	Existing Bearer token. If set, login is skipped.
ITCONS_API_BASE_URL	No	Alternative API base URL.
ITCONS_TIMEZONE	No	Time zone used by itcons_list_today_work_reports. Defaults to Europe/Madrid.

Notes

• Work order pending status is 4.
• itcons_search_workorders fetches /workorders and applies filters locally.
• itcons_list_work_reports_by_date filters on the date field returned by /2.0/partes.
• itcons_create_workorder sends status: 4 and isArchived: 0.
• itcons_create_user sends an array payload to /2.0/users, matching the current API.
• itcons_create_client sends an array payload to /clients and returns the first array item when applicable.

Development

Run syntax checks:

npm run check

Run a local MCP discovery smoke test:

npm run smoke

Run a live read-only smoke test against Itcons.app:

ITCONS_DOMAIN=demo \
ITCONS_USERNAME=[e-mail] \
ITCONS_PASSWORD=change-me \
npm run smoke:live

Publish the public npm package:

npm publish --access public

Security

Do not commit .env files or real credentials. The package excludes .env, node_modules, and debug logs from npm publication.

Create tools perform real writes in Itcons.app. Use them only with credentials and installations where the MCP client is allowed to make changes.