Content
# MaxStat MCP
[](https://modelcontextprotocol.io/)
[](#tool-list)
[](CHANGELOG.md)
[](LICENSE)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.fbmdata%2Fmaxstat-mcp)
[](https://glama.ai/mcp/connectors/io.github.fbmdata/maxstat-mcp)
**Official remote MCP server by MaxStat for search, analytics, and monitoring of channels and posts in the MAX messenger.**
Developer and operator: **FBM Analytics**.
[English](#english) ·
[Get a free API token](https://maxstat.ru/dashboard/api) ·
[Connect MaxStat MCP](#quick-start) ·
[View all 21 tools](#tool-list) ·
[Instructions for AI installer](llms-install.md)
> MaxStat hosts and maintains the MCP server. The repository contains manifests, plugins, analytical skills, client configurations, and documentation. The server implementation and data are not open-source.
## English
### What can be obtained through MaxStat MCP
The AI agent connects to a live index of MAX channels and posts and receives structured data, not search snippets or manually collected screenshots.
| Area | What data does MCP return? |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Channel search | Name, description, URL, category, access type, audience and post ranges, relevance, date or audience sorting |
| Channel card | ID, name, description, avatar, URL, public or private access, subscribers, posts, categories, dates, and RKН status |
| Audience dynamics | Daily values, minimum, maximum, absolute and percentage growth for a selected period |
| Views and reactions | Total, average, and maximum values per post and daily history |
| Channel activity | Number of posts, daily history, and distribution by text, photo, video, files, and other formats |
| Post search | Full-text search with filters by channel, format, dates, views, and reactions |
| Post card | Text, URL, type, attachments, views, sum and breakdown of reactions, dates, and forwarding source |
| Post history | Daily views and reactions history |
| Forwardings | Found reposts, their URLs, dates, and destination channel IDs |
| Monitoring | Webhook for new channel posts or new posts by keyword and category |
| Tariff and expenses | Tariff status, period, included, purchased, used, and remaining credits and charge history |
You can also add a public or invitation-only MAX channel to the MaxStat monitoring queue.
### Verified index scale
| Verified on July 29, 2026 | Live index |
| --------------------------- | -------------: |
| MAX channels | **408 501** |
| Posts | **86 315 758** |
| Channel categories | **42** |
| MCP tools | **21** |
These are production indicators on `maxstat.ru`, not the staging environment. The index is constantly growing. Use `search_channels`, `search_posts`, and `get_categories` to get up-to-date results.
### Quick start
1. Create a token in your [MaxStat API personal account](https://maxstat.ru/dashboard/api).
2. Do not publish the token or add it to Git.
3. Choose a platform below.
4. Restart the client and check that 21 MaxStat tools are available.
| Parameter | Value |
| -------------------- | ---------------------------- |
| Endpoint | `https://maxstat.ru/api/mcp` |
| Transport | Streamable HTTP |
| Authorization | API token |
| Header | `X-API-Token: <API_TOKEN>` |
| Environment variable | `MAXSTAT_API_TOKEN` |
### Installation by platform
| Platform | Method |
| ----------------------- | ------------------------------------------------------- |
| Codex / ChatGPT desktop | Marketplace and native Codex plugin |
| Claude Code | Claude-compatible marketplace |
| VS Code | Agent Plugins marketplace or direct `.vscode/mcp.json` |
| GitHub Copilot CLI | General Claude/Copilot marketplace |
| Gemini CLI | Gemini extension with protected token setting |
| Cursor | Installation via link or `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| JetBrains AI Assistant | IDE MCP settings |
| Claude Desktop | Local bridge `mcp-remote` |
| Cline | Remote Streamable HTTP from `llms-install.md` |
| Other clients | Universal Streamable HTTP JSON |
#### Codex
Before running Codex, save the token in the environment:
```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
```
Add the marketplace and install the plugin:
```bash
codex plugin marketplace add fbmdata/maxstat-mcp
codex plugin add maxstat@maxstat-plugins
```
The plugin connects MCP with the correct custom header `X-API-Token`. Do not use Bearer settings: it sends a different header and is not suitable for MaxStat.
For direct installation without a plugin, combine [`configs/codex.toml`](configs/codex.toml) with your `~/.codex/config.toml`:
```toml
[mcp_servers.maxstat]
url = "https://maxstat.ru/api/mcp"
env_http_headers = { "X-API-Token" = "MAXSTAT_API_TOKEN" }
```
#### Claude Code
```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
claude plugin marketplace add fbmdata/maxstat-mcp
claude plugin install maxstat@maxstat-plugins
```
Direct configuration is located in [`configs/claude-code.json`](configs/claude-code.json).
#### Visual Studio Code
Add the marketplace to `settings.json`:
```json
{
"chat.plugins.marketplaces": ["fbmdata/maxstat-mcp"]
}
```
Open Extensions, find `@agentPlugins`, select `MaxStat MCP`, and click Install. For direct connection, copy [`configs/vscode.json`](configs/vscode.json) to `.vscode/mcp.json`: VS Code will safely request the token via password input.
#### GitHub Copilot CLI
```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
copilot plugin marketplace add fbmdata/maxstat-mcp
copilot plugin install maxstat@maxstat-plugins
```
Claude Code, VS Code, and GitHub Copilot CLI use one compatible plugin, skill, and MCP configuration.
#### Gemini CLI
```bash
gemini extensions install https://github.com/fbmdata/maxstat-mcp
```
The extension will request `MAXSTAT_API_TOKEN` as a sensitive setting and connect it to the `X-API-Token` header. Gemini instructions are in [`GEMINI.md`](GEMINI.md).
#### Cursor
[](https://cursor.com/en/install-mcp?name=maxstat&config=eyJ1cmwiOiJodHRwczovL21heHN0YXQucnUvYXBpL21jcCIsImhlYWRlcnMiOnsiWC1BUEktVG9rZW4iOiIke2VudjpNQVhTVEFUX0FQSV9UT0tFTn0ifX0%3D)
Before running Cursor, set `MAXSTAT_API_TOKEN`, then click the button above.
Alternative: combine [`configs/cursor.json`](configs/cursor.json) with `~/.cursor/mcp.json`.
#### Cline
Set `MAXSTAT_API_TOKEN` before running Cline and pass the agent [`llms-install.md`](llms-install.md). The file contains the remote Streamable HTTP server configuration and connection check. No local npm package is needed: MaxStat hosts and maintains the server on `https://maxstat.ru/api/mcp`.
#### Windsurf
Set `MAXSTAT_API_TOKEN` before running Windsurf and merge
[`configs/windsurf.json`](configs/windsurf.json) with
`~/.codeium/windsurf/mcp_config.json`. The configuration uses native
`${env:MAXSTAT_API_TOKEN}` substitution.
#### JetBrains AI Assistant
Open **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**,
add the HTTP configuration from
[`configs/jetbrains.json`](configs/jetbrains.json) and replace `<API_TOKEN>`
locally in the IDE. JetBrains does not yet document environment variable
substitution in MCP headers, so the placeholder is left intentionally.
#### Claude Desktop
The cloud custom connector Claude does not accept an arbitrary custom
`X-API-Token`. Until OAuth 2.1 is implemented, use the local bridge from
[`configs/claude-desktop.json`](configs/claude-desktop.json). Node.js and npm
are required; the token is stored only in the local Claude Desktop configuration.
#### Generic Configuration
Use [`configs/generic-mcp.json`](configs/generic-mcp.json):
```json
{
"mcpServers": {
"maxstat": {
"type": "streamable-http",
"url": "https://maxstat.ru/api/mcp",
"headers": {
"X-API-Token": "<API_TOKEN>"
}
}
}
}
```
### All 21 Tools
#### Search and Directory
| Tool | What it returns or does | Credits |
| ----------------- | ---------------------------------------------------------------- | --------: |
| `get_categories` | Categories and current number of channels in each category | Free |
| `search_channels` | Filtered, sorted, and paginated channel cards | 3 |
| `get_channel` | Full card of one channel by identifier | 1 |
| `add_channel` | Adds a public or invite-only channel to the queue | Free |
| `search_posts` | Filtered, sorted, and paginated posts | 3 |
#### Channel Analytics
| Tool | What it returns | Credits |
| ------------------------- | ----------------------------------------------------------------- | ------: |
| `get_channel_subscribers` | Min, max, absolute and percentage growth and daily history | 5 |
| `get_channel_views` | Total, average and max views and daily history | 5 |
| `get_channel_likes` | Total, average and max reactions and daily history | 5 |
| `get_channel_posts` | Number of posts, formats and daily activity history | 5 |
#### Post Analytics
| Tool | What it returns | Credits |
| ---------------- | ------------------------------------------------------------------ | ------: |
| `get_post` | Content, attachments, metrics, referrer and detected reposts | 1 |
| `get_post_views` | Current view count and daily history | 5 |
| `get_post_likes` | Total reactions, breakdown by type and daily history | 5 |
#### Webhook Monitoring
| Tool | What it returns or does | Credits |
| ----------------------------- | --------------------------------------------------------------- | --------------------------------: |
| `create_channel_subscription` | Subscribes a public HTTPS callback to new channel posts | Creation free; 2 per delivery |
| `create_keyword_subscription` | Subscribes a callback to posts by query and category | Creation free; 3 per delivery |
| `get_subscriptions` | List of subscriptions with filters by status and type | Free |
| `get_subscription` | One subscription, delivery status and last error | Free |
| `update_subscription` | Changes callback URL, pauses or resumes | Free |
| `delete_subscription` | Deletes a webhook subscription | Free |
The webhook must be available at a public HTTPS address.
#### Plan and Usage
| Tool | What it returns | Credits |
| -------------------------- | ---------------------------------------------------------- | --------: |
| `get_account_subscription` | Plan, status, period and credit state | Free |
| `get_account_limits` | Included, purchased, used and remaining credits | Free |
| `get_account_usage` | Paginated history of query-level charges | Free |
### Example on Real Data
A check request to production on July 29, 2026 returned:
- channel **MAX • Анонсы** with an audience of 3,496,789 subscribers;
- growth from 3,054,001 to 3,496,789 from June 30 to July 29: **+442,788 / +14.5%**;
- [post](https://max.ru/max_news/AZ70lsF7P0s) with **17,888,688 views** and **187,460 reactions**;
- reaction breakdown, daily view and reaction histories;
- 184 detected forwards.
Values show the structure of a real response and are not a promise
of fixed product metrics.
### Query Examples
```text
Find 20 tech MAX channels with the maximum subscriber growth over
the last 30 days. Return links, current audience and growth percentage.
```
```text
Compare five channels by audience, average views, reactions, posting
frequency and format distribution.
```
```text
Find posts about mortgages from July. Return links, text, attachments, views,
detailed reactions and detected forwards.
```
```text
Subscribe a webhook to new posts with the words "artificial intelligence" in
the "Technology" category.
```
```text
Show my MaxStat plan, credit balance and last 10 query charges.
```
### Pricing and Security
MCP is included in all [MaxStat API plans](https://maxstat.ru/promo/api) without
extra charge. MCP and direct API calls use a shared credit balance.
Test Drive is activated on the first API request and provides 1,000 credits
every 30 days.
Never publish a real API token in issues, PRs, configurations, logs or
screenshots. Report security issues according to
[`SECURITY.md`](SECURITY.md).
## English
MaxStat MCP gives AI agents structured access to the live MAX messenger channel
and publication index. It supports channel and post discovery, daily audience,
view and reaction histories, publishing activity, attachment and reaction
details, forward detection, webhook monitoring, and account credit usage.
The production index was verified on July 29, 2026 with 408,501 channels,
86,315,758 posts, 42 channel categories, and 21 MCP tools.
### Connection
| Parameter | Value |
| --------------- | ------------------------------------------------------------ |
| Endpoint | `https://maxstat.ru/api/mcp` |
| Transport | Streamable HTTP |
| Header | `X-API-Token: <API_TOKEN>` |
| Token dashboard | [maxstat.ru/dashboard/api](https://maxstat.ru/dashboard/api) |
### Install
#### Codex
```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
codex plugin marketplace add fbmdata/maxstat-mcp
codex plugin add maxstat@maxstat-plugins
```
#### Claude Code
```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
claude plugin marketplace add fbmdata/maxstat-mcp
claude plugin install maxstat@maxstat-plugins
```
#### GitHub Copilot CLI
```bash
export MAXSTAT_API_TOKEN="<API_TOKEN>"
copilot plugin marketplace add fbmdata/maxstat-mcp
copilot plugin install maxstat@maxstat-plugins
```
#### Gemini CLI
```bash
gemini extensions install https://github.com/fbmdata/maxstat-mcp
```
For VS Code, Cursor, Windsurf, JetBrains AI Assistant, Claude Desktop, and
generic clients, use the checked-in [`configs/`](configs/) directory. The
Russian section above contains detailed client-specific instructions.
### Capabilities
- Search and filter MAX channels and publications.
- Retrieve channel profiles, audience growth, views, reactions, activity, and
content-format mix.
- Retrieve post text, attachments, metrics, reaction details, histories, and
detected forwards.
- Create and manage channel or keyword webhook subscriptions.
- Inspect the active MaxStat plan, credit balance, and request-level usage.
The complete 21-tool contract and credit costs are documented in
[All 21 Tools](#all-21-tools).
### Authentication boundary
This release supports clients that can send the custom `X-API-Token` header.
Publishing as a fully hosted ChatGPT or Claude cloud connector requires a
separate OAuth 2.1 implementation.
## Links
- [MaxStat MCP](https://maxstat.ru/promo/mcp)
- [Get a token](https://maxstat.ru/dashboard/api)
- [API documentation](https://maxstat.ru/api/docs)
- [API plans](https://maxstat.ru/promo/api)
- [FBM Analytics](https://fbmdata.ru)
- [MaxStat Insights in MAX](https://max.ru/maxstat)
- [FBM API Insights on Telegram](https://t.me/fbmapi)
## License
MIT applies only to manifests, plugins, skills, configurations, documentation, and
auxiliary checks published in this repository. The license does not apply to the
MaxStat service, API, data, databases, trademarks, and server-side implementation.
Details are provided in [`NOTICE`](NOTICE).
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available