Funstat MCP (Go)

This project is a complete Go reimplementation of the original Funstat MCP server. It exposes the same MCP tools wrapped around the Telegram @openaiw_bot, but with a native Go runtime and HTTP transport.

Features

• Streamable HTTP transport (/sse + /messages) compatible with MCP clients such as Codex CLI, Cursor, and Claude Code.
• Full parity with the original nine Funstat tools (search, topchat, text, human lookup, user info, user messages, balance, menu, start).
• Built-in rate limiting and response caching to stay within Telegram limits.
• Telegram session bootstrapping from a Telethon string session or persisted Go session storage.
• Configurable proxy, cache TTL, and rate limit settings via environment variables.

Requirements

• Go 1.22 or newer (the module was developed with Go 1.24).
• A valid Telegram API ID and API hash.
• A logged-in Telegram session. The Go server expects either:
  • TELEGRAM_SESSION_STRING (or TELEGRAM_SESSION_STRING_FILE) containing a Telethon StringSession, which will be converted automatically into Go session storage, or
  • TELEGRAM_SESSION_PATH pointing to a Go session file created by this service on a previous run (~/.funstatmcp/session.json by default).
• Network access to Telegram (configure proxies via the FUNSTAT_PROXY_* variables if necessary).

Environment Variables

Variable	Description
TELEGRAM_API_ID	Required. Telegram API ID.
TELEGRAM_API_HASH	Required. Telegram API hash.
TELEGRAM_SESSION_STRING	Base64 Telethon StringSession (optional if session file already exists).
TELEGRAM_SESSION_STRING_FILE	Path to a file containing the StringSession.
TELEGRAM_SESSION_PATH	Optional path for Go session storage (.session suffix is appended if missing).
FUNSTAT_BOT_USERNAME	Bot username (default @openaiw_bot).
FUNSTAT_RATE_LIMIT_PER_SECOND	Requests per second (default 18).
FUNSTAT_RATE_LIMIT_WINDOW	Duration window, e.g. 1s (default 1s).
FUNSTAT_CACHE_TTL	Cache lifetime for command responses (default 1h).
FUNSTAT_PROXY_TYPE	Proxy type (socks5 supported).
FUNSTAT_PROXY_HOST	Proxy host.
FUNSTAT_PROXY_PORT	Proxy port.
FUNSTAT_PROXY_USERNAME / FUNSTAT_PROXY_PASSWORD	Optional proxy credentials.
FUNSTAT_HOST	Bind host (default 127.0.0.1).
FUNSTAT_PORT	Bind port (default 8091).
FUNSTAT_REQUIRE_SESSION	When true, enables strict session ID enforcement (not yet required by the Go transport).

Running the Server

export TELEGRAM_API_ID=...
export TELEGRAM_API_HASH=...
export TELEGRAM_SESSION_STRING=... # or TELEGRAM_SESSION_STRING_FILE

go run ./cmd/funstat-mcp

The server starts on http://127.0.0.1:8091 by default with:

• GET /sse — server-sent events stream for MCP clients.
• POST /messages — JSON-RPC 2.0 endpoint for MCP requests.
• GET /health — simple health probe.

For convenience a helper script is available:

./scripts/start_server.sh

Tool Coverage

The server exposes the following MCP tools (identical to the Python version):

Tool	Description
funstat_search	搜索 Telegram 群组/频道。
funstat_topchat	获取热门群组列表。
funstat_text	按文本搜索消息。
funstat_human	按姓名搜索用户。
funstat_user_info	查询用户详情。
funstat_user_messages	抓取用户聊天记录并自动翻页。
funstat_balance	查询积分余额。
funstat_menu	显示 Funstat 菜单。
funstat_start	Funstat 欢迎信息。

Session Notes

• If you already possess the Telethon .session SQLite file, generate a StringSession first (e.g. via Telethon or python -m telethon.sessions) and provide it through TELEGRAM_SESSION_STRING.
• After the first successful run the Go server stores an encrypted Go session at ~/.funstatmcp/session.json (unless overridden). Subsequent runs only require the API ID/hash.

Development

• Format code with gofmt -w cmd internal.
• Run go test ./... (no automated tests are included yet).
• Dependencies are managed via Go modules (go mod tidy).

License

Follows the license of the original Funstat MCP project (MIT, if applicable).