Iitc

Bridge between IITC (Ingress Intel Total Conversion) and MCP (Model Context Protocol) agents. Let your AI assistant see the map, count portals, track players, and talk to COMM — without touching a mouse.

Quick Start

1. Install Userscript

Install IITC first, then add the iitc-mcp userscript in Tampermonkey:

https://github.com/comicchang/iitc-mcp/releases/latest/download/iitc-mcp.user.js

2. Configure MCP Server for Your Agent

CLI entry:

npx github:comicchang/iitc-mcp serve

Add --read-only for read-only mode (14 tools; omits iitc_send_comm and iitc_redeem_code):

npx github:comicchang/iitc-mcp serve --read-only

Codex (~/.codex/config.toml or project-level .codex/config.toml):

[mcp_servers.iitc-mcp]
command = "npx"
args = ["github:comicchang/iitc-mcp", "serve"]

OpenCode (~/.openCode/mcp.json or project-level .openCode/mcp.json):

{
  "mcpServers": {
    "iitc-mcp": {
      "command": "npx",
      "args": ["github:comicchang/iitc-mcp", "serve"]
    }
  }
}

"iitc-mcp": {
  "type": "stdio",
  "command": "/path/to/node_modules/.bin/tsx",
  "args": ["/path/to/packages/mcp-server/src/cli.ts", "serve"]
}

Reload MCP config and you're set — 16 tools auto-register (14 if server started with --read-only).

Open https://intel.ingress.com. Once both the userscript and MCP server are ready, the MCP indicator in IITC Toolbox turns green.

MCP Tools (16 total)

Usage Examples

Ask your AI assistant in natural language:

Search a region and count portals

搜索静安雕塑公园，统计 portal 状态

iitc_search_region("静安雕塑公园")   → 围框 + 等数据加载
iitc_list_portals                   → 按阵营统绿/蓝/红/白数量

Check a specific portal

青果巷赵宅现在什么颜色，连满 link 了吗

iitc_search("青果巷")               → 找到候选 Portal
iitc_get_portal_details(guid)       → 阵营/等级/血量/linkGuids

See who's been active nearby

附近最近有谁在动

iitc_list_players                   → 玩家名/阵营/最近位置/动作
iitc_get_player_trail("playerName") → 完整轨迹

Find high-value targets

区域内有哪些 L7+ Portal，哪些阵营占领的

iitc_search_region("目标区域")       → 围框
iitc_list_portals                   → 按 level 筛选 L7+

Monitor COMM

看看 COMM 最近在聊什么

iitc_list_comm(channel="all")       → 最近消息

Architecture

Default mode — embedded broker (one agent = one browser session):

graph LR
    US[Userscript] -->|HTTP :27342| S[Server]
    S -->|stdio| AGENT[AI Agent]

Shared mode — standalone broker + multiple MCP servers:

graph LR
    US[Userscript] -->|HTTP :27342| BR[Bridge Broker]
    MCP_A[MCP Server A] -->|/mcp/*| BR
    MCP_B[MCP Server B] -->|/mcp/*| BR
    AGENT_A[AI Agent A] -->|stdio| MCP_A
    AGENT_B[AI Agent B] -->|stdio| MCP_B

iitc-mcp broker                          # start standalone broker
iitc-mcp serve --broker-url http://127.0.0.1:27342   # connect to shared broker

Commands are queued by ID — simultaneous operations may interfere. In practice, only one agent operates at a time.

Three packages:

• packages/protocol — shared Zod schemas
• packages/iitc-plugin — userscript (page adapter + transport)
• packages/mcp-server — Node.js MCP server (broker + HTTP + CLI)

Build & Development

git clone https://github.com/comicchang/iitc-mcp.git
cd iitc-mcp
npm ci --legacy-peer-deps
npm run build && npm test        # 163 tests, typecheck, 3 build artifacts

Daily dev commands:

npm run typecheck    # strict TypeScript
npm run build        # userscript + server
npm run lint         # ESLint
npm test             # unit tests (163)
npm run test:smoke   # no-browser smoke tests

# Start MCP server locally
npx tsx packages/mcp-server/src/cli.ts serve

# Read-only mode
npx tsx packages/mcp-server/src/cli.ts serve --read-only

License

See LICENSE. Fork must preserve the same license. Only Enlightened players may use this software. Resistance and Machina are not welcome. Attempting to bypass these restrictions is prohibited.

Enlightened 💚