Connect AI assistants to Itcons.app to manage work orders, reports, projects, users, and operational resources.
Also known as itcons-app/mcp, mcp, @itcons-app/mcp
- Stars
- 0
- Tools
- 45
- Downloads, 30 days
- 641
- Latest version
- 0.5.1
- Last commit
- Nov 13, 2026
- License
- MIT
What is Itcons.app MCP?
Itcons.app connects AI assistants to Itcons.app to manage work orders, reports, projects, users, and operational resources. It exposes 45 tools, such as itcons_check_connection, itcons_list_users, itcons_get_user.
Summary generated from the project's README
About Itcons.app MCP server
Managing business operations like work orders, projects, and client data through an AI assistant is possible with this MCP server. It connects AI clients to the Itcons.app API v3, allowing users to interact with operational resources, calendars, and work reports. The server supports two distinct deployment modes: a local stdio mode for desktop clients like Claude Desktop and a remote HTTP mode for hosted environments requiring a public HTTPS endpoint.
Users can perform a wide range of tasks using specific tools such as itcons_list_projects, itcons_create_work_order, or itcons_update_user. For environments requiring restricted access, a reports-only profile is available via a dedicated endpoint that limits data exposure and caps list results at 50 items. Setup requires configuring environment variables including the ITCONS_DOMAIN and authentication credentials via username and password or a Bearer token.
What you can do with it
- 1Update project and client detailsAn AI assistant can modify existing client or project information using patch tools.
- 2Track daily work reportsDevelopers can ask an AI to retrieve and list all work reports submitted for the current day.
- 3Access restricted operational dataUse a specialized profile to query work orders and calendars without exposing private user identities or attachments.
Written from the project's README. Every use case is checked against a quote from it.
How to install Itcons.app MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Itcons.app MCP in Claude Code
$ claude mcp add --env 'ITCONS_DOMAIN=<ITCONS_DOMAIN>' --env 'ITCONS_PASSWORD=<YOUR_ITCONS_PASSWORD>' --env 'ITCONS_TOKEN=<YOUR_ITCONS_TOKEN>' mcp -- npx -y @itcons-app/mcpInstall Itcons.app MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@itcons-app/mcp"
],
"env": {
"ITCONS_DOMAIN": "<ITCONS_DOMAIN>",
"ITCONS_PASSWORD": "<YOUR_ITCONS_PASSWORD>",
"ITCONS_TOKEN": "<YOUR_ITCONS_TOKEN>"
}
}
}
}Install Itcons.app MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@itcons-app/mcp"
],
"env": {
"ITCONS_DOMAIN": "<ITCONS_DOMAIN>",
"ITCONS_PASSWORD": "<YOUR_ITCONS_PASSWORD>",
"ITCONS_TOKEN": "<YOUR_ITCONS_TOKEN>"
}
}
}
}Install Itcons.app MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@itcons-app/mcp"],"env":{"ITCONS_DOMAIN":"<ITCONS_DOMAIN>","ITCONS_PASSWORD":"<YOUR_ITCONS_PASSWORD>","ITCONS_TOKEN":"<YOUR_ITCONS_TOKEN>"}}'Install Itcons.app MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@itcons-app/mcp"
],
"env": {
"ITCONS_DOMAIN": "<ITCONS_DOMAIN>",
"ITCONS_PASSWORD": "<YOUR_ITCONS_PASSWORD>",
"ITCONS_TOKEN": "<YOUR_ITCONS_TOKEN>"
}
}
}
}Install Itcons.app MCP in Codex
$ codex mcp add mcp --env 'ITCONS_DOMAIN=<ITCONS_DOMAIN>' --env 'ITCONS_PASSWORD=<YOUR_ITCONS_PASSWORD>' --env 'ITCONS_TOKEN=<YOUR_ITCONS_TOKEN>' -- npx -y @itcons-app/mcpInstall Itcons.app MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@itcons-app/mcp"] [mcp_servers.mcp.env] ITCONS_DOMAIN = "<ITCONS_DOMAIN>" ITCONS_PASSWORD = "<YOUR_ITCONS_PASSWORD>" ITCONS_TOKEN = "<YOUR_ITCONS_TOKEN>"
Install Itcons.app MCP in Gemini CLI
$ gemini mcp add -s user -e 'ITCONS_DOMAIN=<ITCONS_DOMAIN>' -e 'ITCONS_PASSWORD=<YOUR_ITCONS_PASSWORD>' -e 'ITCONS_TOKEN=<YOUR_ITCONS_TOKEN>' mcp npx -- -y @itcons-app/mcpInstall Itcons.app MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@itcons-app/mcp"
],
"env": {
"ITCONS_DOMAIN": "<ITCONS_DOMAIN>",
"ITCONS_PASSWORD": "<YOUR_ITCONS_PASSWORD>",
"ITCONS_TOKEN": "<YOUR_ITCONS_TOKEN>"
}
}
}
}Itcons.app MCP tools 45
Detected from the READMEitcons_check_connectionitcons_list_usersitcons_get_useritcons_list_clientsitcons_get_clientitcons_list_projectsitcons_get_projectitcons_list_categoriesitcons_get_categoryitcons_list_resourcesitcons_get_resourceitcons_list_calendars
| itcons_check_connection | — | |
| itcons_list_users | — | |
| itcons_get_user | — | |
| itcons_list_clients | — | |
| itcons_get_client | — | |
| itcons_list_projects | — | |
| itcons_get_project | — | |
| itcons_list_categories | — | |
| itcons_get_category | — | |
| itcons_list_resources | — | |
| itcons_get_resource | — | |
| itcons_list_calendars | — |
Show all 45 toolsShow fewer tools
itcons_get_calendaritcons_list_leave_typesitcons_list_work_report_templatesitcons_get_work_report_templateitcons_list_work_reportsitcons_get_work_reportitcons_get_work_report_as_post_payloaditcons_list_work_reports_by_dateitcons_list_today_work_reportsitcons_list_work_order_typesitcons_get_work_order_typeitcons_list_work_ordersitcons_get_work_orderitcons_list_statusesitcons_create_useritcons_update_useritcons_create_clientitcons_update_clientitcons_create_projectitcons_update_projectitcons_create_categoryitcons_update_categoryitcons_create_resourceitcons_update_resourceitcons_create_work_reportitcons_update_work_report_metadataitcons_replace_work_report_contentitcons_create_work_orderitcons_update_work_orderitcons_list_holidaysitcons_get_working_daysitcons_list_work_report_modelsitcons_search_work_reports
| itcons_get_calendar | — | |
| itcons_list_leave_types | — | |
| itcons_list_work_report_templates | — | |
| itcons_get_work_report_template | — | |
| itcons_list_work_reports | — | |
| itcons_get_work_report | — | |
| itcons_get_work_report_as_post_payload | — | |
| itcons_list_work_reports_by_date | — | |
| itcons_list_today_work_reports | — | |
| itcons_list_work_order_types | — | |
| itcons_get_work_order_type | — | |
| itcons_list_work_orders | — | |
| itcons_get_work_order | — | |
| itcons_list_statuses | — | |
| itcons_create_user | — | |
| itcons_update_user | — | |
| itcons_create_client | — | |
| itcons_update_client | — | |
| itcons_create_project | — | |
| itcons_update_project | — | |
| itcons_create_category | — | |
| itcons_update_category | — | |
| itcons_create_resource | — | |
| itcons_update_resource | — | |
| itcons_create_work_report | — | |
| itcons_update_work_report_metadata | — | |
| itcons_replace_work_report_content | — | |
| itcons_create_work_order | — | |
| itcons_update_work_order | — | |
| itcons_list_holidays | — | |
| itcons_get_working_days | — | |
| itcons_list_work_report_models | — | |
| itcons_search_work_reports | — |
Configuration
ITCONS_DOMAINRequiredItcons.app tenant domain, for example 'demo' for https://demo.itcons.app.
ITCONS_PASSWORDSecretItcons.app password for local stdio usage.
ITCONS_TOKENSecretExisting Itcons.app bearer token. Can be used instead of username and password.
ITCONS_MCP_PUBLIC_URLITCONS_OAUTH_CLIENT_IDITCONS_OAUTH_CLIENT_SECRETITCONS_TIMEZONETimezone used for date-based queries.
ITCONS_USERNAMEItcons.app username or email for local stdio usage.
| Name | Description | |
|---|---|---|
| ITCONS_DOMAIN | Itcons.app tenant domain, for example 'demo' for https://demo.itcons.app. | Required |
| ITCONS_PASSWORD | Itcons.app password for local stdio usage. | Secret |
| ITCONS_TOKEN | Existing Itcons.app bearer token. Can be used instead of username and password. | Secret |
| ITCONS_MCP_PUBLIC_URL | — | |
| ITCONS_OAUTH_CLIENT_ID | — | |
| ITCONS_OAUTH_CLIENT_SECRET | — | |
| ITCONS_TIMEZONE | Timezone used for date-based queries. | |
| ITCONS_USERNAME | Itcons.app username or email for local stdio usage. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubItcons.app MCP Server
Model Context Protocol server for connecting AI assistants to Itcons.app API v3.
Itcons.app is a business operations platform for managing work reports, work orders, projects, clients, users, calendars, categories, and operational resources.
This package can run in two modes:
- Local
stdiomode for clients such as Codex, Claude Desktop, and other local MCP hosts. - Remote HTTP mode for hosted MCP clients or other clients that require a public HTTPS MCP endpoint.
The MCP uses the existing Itcons.app username/password login flow (POST /api/login_check) and then calls API v3 with Bearer authentication.
Features
- Resolve the tenant from
ITCONS_DOMAIN. - Call API v3 under
https://{ITCONS_DOMAIN}.itcons.app/api/v3. - List and get users, clients, projects, categories, resources, calendars, leave types, work report templates, work reports, work order types, and work orders.
- Create and patch API v3 users, clients, projects, categories, resources, work reports, and work orders.
- Keep the existing reports-only HTTP profile at
/reports-mcpfor the current ChatGPT connector.
Webhooks are intentionally not exposed as MCP tools. API v3 documents webhook payloads as outbound deliveries configured inside Itcons.app.
Installation
From npm:
npm install -g @itcons-app/mcp
From this repository:
npm install
npm run check
Configuration
The local stdio server reads Itcons.app credentials from environment variables.
ITCONS_DOMAIN=demo
ITCONS_USERNAME=user@example.com
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/v3
If ITCONS_API_BASE_URL ends in /api, the server appends /v3 automatically.
MCP Client Example
{
"mcpServers": {
"itcons-app": {
"command": "itcons-app-mcp",
"env": {
"ITCONS_DOMAIN": "demo",
"ITCONS_USERNAME": "user@example.com",
"ITCONS_PASSWORD": "change-me",
"ITCONS_TIMEZONE": "Europe/Madrid"
}
}
}
}
Remote HTTP Server
Start the remote MCP server:
PORT=3000 \
HOST=127.0.0.1 \
ITCONS_MCP_PUBLIC_URL=https://mcp.example.com \
ITCONS_OAUTH_CLIENT_ID=itcons-app-chatgpt \
ITCONS_OAUTH_CLIENT_SECRET=change-me \
npm run start:http
The remote server exposes:
- MCP Streamable HTTP endpoint:
https://mcp.example.com/mcp - Reports-only MCP endpoint:
https://mcp.example.com/reports-mcp - SSE-compatible endpoint:
https://mcp.example.com/sse - OAuth authorize URL:
https://mcp.example.com/oauth/authorize - OAuth token URL:
https://mcp.example.com/oauth/token - OAuth dynamic client registration URL:
https://mcp.example.com/oauth/register - Health check:
https://mcp.example.com/health
When a user connects through OAuth, the login page asks for the Itcons.app email/password and domain. If ITCONS_DOMAIN_LOOKUP_URL is configured, the page can detect the domain from the email.
Tools
Read-only tools:
itcons_check_connectionitcons_list_usersitcons_get_useritcons_list_clientsitcons_get_clientitcons_list_projectsitcons_get_projectitcons_list_categoriesitcons_get_categoryitcons_list_resourcesitcons_get_resourceitcons_list_calendarsitcons_get_calendaritcons_list_leave_typesitcons_list_work_report_templatesitcons_get_work_report_templateitcons_list_work_reportsitcons_get_work_reportitcons_get_work_report_as_post_payloaditcons_list_work_reports_by_dateitcons_list_today_work_reportsitcons_list_work_order_typesitcons_get_work_order_typeitcons_list_work_ordersitcons_get_work_orderitcons_list_statuses
Write tools:
itcons_create_useritcons_update_useritcons_create_clientitcons_update_clientitcons_create_projectitcons_update_projectitcons_create_categoryitcons_update_categoryitcons_create_resourceitcons_update_resourceitcons_create_work_reportitcons_update_work_report_metadataitcons_replace_work_report_contentitcons_create_work_orderitcons_update_work_order
Reports-only profile tools exposed by /reports-mcp:
itcons_check_connectionitcons_list_calendarsitcons_list_holidaysitcons_get_working_daysitcons_list_leave_typesitcons_list_projectsitcons_list_work_ordersitcons_list_work_report_modelsitcons_search_work_reportsitcons_list_work_reports_by_dateitcons_list_today_work_reports
The reports-only profile keeps its previous work-report tool names for compatibility and adds bounded read-only operational queries. Project and work-order results are reduced to operational fields and exclude notes, user identities, locations, attachments, client details and other unnecessary private data. Public-profile list calls are capped at 50 items, and calendar calculations accept at most 366 inclusive days.
Patch tools accept a payload object with the exact API v3 fields documented by the Postman collection. This keeps the MCP aligned with the API without hiding partial update features such as add and remove operations.
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 v3 base URL. |
ITCONS_TIMEZONE |
No | Time zone used by itcons_list_today_work_reports. Defaults to Europe/Madrid. |
PORT |
No | HTTP server port. Defaults to 3000. |
HOST |
No | HTTP server bind host. Defaults to 127.0.0.1. |
ITCONS_MCP_PUBLIC_URL |
Yes for remote mode | Public HTTPS origin, for example https://mcp.example.com. |
ITCONS_MCP_PATH |
No | Remote MCP endpoint path. Defaults to /mcp. |
ITCONS_REPORTS_MCP_PATH |
No | Reports-only MCP endpoint path. Defaults to /reports-mcp. |
ITCONS_MCP_SSE_PATH |
No | SSE-compatible endpoint path. Defaults to /sse. |
ITCONS_MCP_ALLOWED_HOSTS |
Recommended for remote mode | Comma-separated allowed Host headers, for example mcp.example.com. |
ITCONS_OAUTH_CLIENT_ID |
No | OAuth client ID expected by the remote server. Defaults to itcons-app-chatgpt. |
ITCONS_OAUTH_CLIENT_SECRET |
Recommended for remote mode | OAuth client secret expected by the remote server. |
ITCONS_OAUTH_CLIENTS_FILE |
Recommended for public apps | JSON file used to persist dynamically registered OAuth clients. |
ITCONS_OAUTH_STATE_FILE |
Required for restart-safe OAuth | Encrypted state file for access and refresh token sessions. |
ITCONS_OAUTH_STATE_SECRET |
Required with the state file | Long random secret used to encrypt OAuth state at rest. |
ITCONS_DOMAIN_LOOKUP_URL |
No | Endpoint used to detect the Itcons.app domain from an email. Defaults to https://autov2.itcons.app/webhook/my-domain. |
ITCONS_HTTP_AUTH_DISABLED |
No | Set to 1 only for local HTTP smoke tests. Disables remote MCP bearer auth. |
Development
Run syntax checks:
npm run check
Run a local MCP discovery smoke test:
npm run smoke
Run a local HTTP MCP smoke test:
npm run smoke:http
Run a live read-only smoke test against Itcons.app:
ITCONS_DOMAIN=demo \
ITCONS_USERNAME=user@example.com \
ITCONS_PASSWORD=change-me \
npm run smoke:live
Run a live read-only HTTP smoke test against Itcons.app:
ITCONS_DOMAIN=demo \
ITCONS_USERNAME=user@example.com \
ITCONS_PASSWORD=change-me \
npm run smoke:http:live
Run a live OAuth smoke test that simulates a hosted-client connection:
ITCONS_DOMAIN=demo \
ITCONS_USERNAME=user@example.com \
ITCONS_PASSWORD=change-me \
npm run smoke:oauth:live
Security
Do not commit .env files or real credentials. The package excludes .env, node_modules, and debug logs from npm publication.
Write tools perform real changes in Itcons.app. Use them only with credentials and installations where the MCP client is allowed to make changes.
For remote deployments, configure ITCONS_OAUTH_STATE_FILE and ITCONS_OAUTH_STATE_SECRET. Access and refresh token state is then encrypted at rest and survives process restarts. Authorization codes remain short-lived and in memory.
The file-backed OAuth state is designed for a single Node.js process. Use a shared transactional store before running multiple replicas.
Itcons.app MCP questions
How do I add Itcons.app MCP to Claude Code?
Run claude mcp add --env 'ITCONS_DOMAIN=<ITCONS_DOMAIN>' --env 'ITCONS_PASSWORD=<YOUR_ITCONS_PASSWORD>' --env 'ITCONS_TOKEN=<YOUR_ITCONS_TOKEN>' mcp -- npx -y @itcons-app/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Itcons.app MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Itcons.app MCP provide?
It exposes 45 tools, including itcons_check_connection, itcons_list_users, itcons_get_user, itcons_list_clients, itcons_get_client.
How can I run the Itcons.app MCP server locally?
You can run it in local stdio mode for clients like Claude Desktop or Codex by configuring your environment variables.
Does the server support remote connections?
Yes, it supports a remote HTTP mode for hosted MCP clients or any client requiring a public HTTPS endpoint.