IITC-MCP

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"]
    }
  }
}

<details> <summary>Oh My Pi local dev config</summary>

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

</details>

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)

Tool	Description
iitc_get_map_state	Map center, zoom, bounds, selected portal
iitc_set_map_view	Set map center and zoom
iitc_fit_map_bounds	Fit map to bounding box
iitc_search_region	Search named region via Nominatim → fit bounds → wait for data
iitc_list_portals	List portals in viewport (paginated)
iitc_list_links	List links in viewport (paginated)
iitc_list_fields	List control fields in viewport (paginated)
iitc_get_portal_details	Portal detail: mods, resonators, link/field GUIDs
iitc_select_portal	Select a portal on the map
iitc_search	Search portals by name
iitc_list_comm	Read COMM messages
iitc_send_comm	Send COMM message
iitc_redeem_code	Redeem a passcode
iitc_get_self	Your own faction, level, AP, XM
iitc_list_players	Tracked players with last position (Player Tracker)
iitc_get_player_trail	Single player's trail with timestamps

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 💚