ai-manage-tools MCP

AI Manager MCP (Model Context Protocol) tool for AI assistants. It collects local Codex and Claude Code usage and uploads it to AI Manager.

Cursor usage is not collected through MCP. Upload Cursor Usage CSV and Invoice/Receipt files from the AI Manager self-reporting page instead.

Requirements

• Node.js 18+
• Python 3.11+
• AI Manager upload token

If Python is not available as python3.12, python3.11, or python3, set AI_MANAGE_TOOLS_PYTHON.

Install

You usually do not need to install it globally. Configure your AI tool to run it through npx:

npx -y @longshineai/ai-manage-tools@latest

Environment

AI_MANAGER_TOKEN=aim_xxx
# Optional: override the built-in production base URL (default: https://token.longshine.com/ai-manage).
# AI_MANAGER_BASE_URL=https://token.longshine.com/ai-manage
# Optional: disable background collection from the MCP server.
AI_MANAGER_AUTO_COLLECT=false

• AI_MANAGER_TOKEN: upload token issued by AI Manager.
• AI_MANAGER_BASE_URL: optional override; defaults to https://token.longshine.com/ai-manage.
• AI_MANAGE_TOOLS_PYTHON: optional Python interpreter path.
• AI_MANAGER_AUTO_COLLECT: optional. Defaults to enabled; set to false to disable background collection.
• AI_MANAGER_MAX_UPLOAD_RECORDS_PER_BATCH: optional. Defaults to 1000 records.
• AI_MANAGER_MAX_UPLOAD_BYTES_PER_BATCH: optional. Defaults to 1000000 serialized bytes.
• AI_MANAGER_MAX_UPLOAD_BATCHES_PER_CYCLE: optional. Defaults to 10 sequential batches.
• Background collection uses local scheduler and collect locks, so only one ai-manage-tools process schedules and runs collection at a time on the same computer.
• Pending Codex or Claude Code spool data is drained before that source is collected again. Oversized legacy spool files are uploaded in lossless chunks and rewritten only after each chunk is accepted. Corrupt or unreadable payloads are moved to spool/quarantine so later collection can continue.

Codex

Add this MCP server to your Codex config:

[mcp_servers.ai-manage-tools]
command = "npx"
args = ["-y", "@longshineai/ai-manage-tools@latest"]

[mcp_servers.ai-manage-tools.env]
AI_MANAGER_TOKEN = "aim_xxx"

Then ask Codex to call the status tool.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "ai-manage-tools": {
      "command": "npx",
      "args": ["-y", "@longshineai/ai-manage-tools@latest"],
      "env": {
        "AI_MANAGER_TOKEN": "aim_xxx"
      }
    }
  }
}

Restart Claude Desktop after editing the file.

Tools

| Tool | Purpose | | --- | --- | | status | Check base URL and whether AI_MANAGER_TOKEN is present. | | report | Upload a Codex or Claude Code JSONL usage fixture. | | collect | Collect a bounded Codex or Claude Code usage batch and upload it. | | doctor | Run a lightweight local diagnostic. | | backfill | Backfill Codex or Claude Code local usage. |

CLI fallback

The package also keeps a direct CLI mode:

AI_MANAGER_TOKEN=aim_xxx ai-manage-tools status --base-url https://token.longshine.com/ai-manage
ai-manage-tools report --host codex --fixture ./sample.jsonl --base-url https://token.longshine.com/ai-manage

For MCP clients, prefer the npx configuration above.