@tgsystem/mcp-user

MCP (Model Context Protocol) server that lets end-users of TGSystem access their own signage devices, content, and permissions from any MCP-compatible AI client — Claude Desktop, Cursor, ChatGPT (via plugins), and others.

This package is a thin wrapper over the public TGSystem JSON API. It runs locally on the user's machine via stdio transport and forwards each tool call to service-api.tgsystem.kr using the user's JWT.

Read-only release (v0.1.x). Only three L0 (read-only) tools are exposed: tg_devices_list, tg_perms_me, tg_perms_risk. Write / delete / billing tools will arrive after the read path is verified end-to-end.

Install / Setup

The package is designed to be run via npx, so end users do not install it explicitly. Add it to your MCP client config:

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "tgsystem": {
      "command": "npx",
      "args": ["-y", "@tgsystem/mcp-user"],
      "env": {
        "TGSYSTEM_API": "https://service-api.tgsystem.kr/v1/tgsystem",
        "TGSYSTEM_TOKEN": "<your TGSystem JWT>"
      }
    }
  }
}

How to get the token:

1. Open https://service.tgsystem.kr
2. Log in (or create an account)
3. Sidebar → AI Connect Guide → copy the JWT token shown there
4. Paste it as TGSYSTEM_TOKEN
5. Restart Claude Desktop

After restart, Claude can call any of the tools below.

Cursor / other MCP clients

The MCP entrypoint is tgsystem-mcp-user (defined in package.json bin). Most clients accept the same command / args / env shape shown above; consult your client's MCP docs.

Tools

All three tools are read-only. None can modify, delete, or charge anything on your account.

| Name | Description | Endpoint | |------|------|----------| | tg_devices_list | List the signage devices registered to the authenticated user. | GET /accounts/me/devices | | tg_perms_me | Show the user's currently active MCP preset and the effective scopes the server will accept. | GET /mdp/perms/me | | tg_perms_risk | Return the MCP risk-level catalog (L0–L3) for every published scope, including which scopes need a magic-link email confirmation. | GET /mdp/perms/risk |

Each tool is hand-defined with proper MCP annotations (readOnlyHint: true), so MCP clients that respect annotations (Claude Desktop directory, Cursor, …) can render them as safe.

Permission model

TGSystem's MCP permission system is the source of truth. This package only forwards calls — it does not decide what the user is allowed to do.

• Presets: safe / standard / power (and two more configurable in the operator console)
• Effective scopes: default_preset(role) ∩ tenant_cap ∩ user_override
• Risk levels: L0 (read) → L3 (delete / billing — requires an out-of-band magic-link email confirmation)
• Audit: every tool call hits the server, which writes a row to mdp_audit regardless of outcome

If a tool returns permission_denied, change the active preset under AI Permissions in https://service.tgsystem.kr instead of editing this package.

Errors

| Code | Meaning | |------|---------| | missing_token | TGSYSTEM_TOKEN env var is empty — paste your JWT | | authentication_failed | Token is invalid or expired — re-copy from AI Connect Guide | | permission_denied | Your active MCP preset does not allow the requested scope | | network_error | The server could not be reached | | http_<status> | The server returned an unexpected status; details in body |

Errors are returned as MCP content with isError: true, so the client can show them inline. The package does not retry, fall back to a different endpoint, or guess.

Development

git clone https://github.com/tgsystem/mcp-user.git
cd mcp-user
npm install

# point at a real backend with a real JWT
TGSYSTEM_TOKEN=<jwt> npm run test:local

npm run test:local runs src/smoke.js, which calls all three endpoints directly (no MCP transport) and prints PASS/FAIL per tool. Use it before publishing.

To verify the full MCP path manually, register this package locally with Claude Desktop using a file: path:

{
  "mcpServers": {
    "tgsystem-local": {
      "command": "node",
      "args": ["D:/tgsystem-mcp-user/src/index.js"],
      "env": {
        "TGSYSTEM_TOKEN": "<jwt>"
      }
    }
  }
}

What's NOT in this release

By design, none of these are included in v0.1.x:

• Write tools (content upload, schedule changes, …)
• Delete tools (device removal, member removal, …)
• Billing tools (subscription changes, refunds, …)
• Remote Streamable HTTP transport / OAuth flows
• Auto-generation of tools from the TGSystem OpenAPI spec
• Any modification of the backend or operational devices

These are tracked as separate milestones and will land in v0.2.x and later, after the read-only surface has been validated end-to-end with real users and audited via mdp_audit.

License

MIT — see LICENSE.