axomind-mcp

Principle

The MCP lives on the consumer side, not on the Axomind server. It contains no business logic — it makes an HTTP POST to bot_api.php with id_bot + key_access and returns the JSON. All security (auth, rate limiting, IP bans, bots @> checks) stays on the PHP side.

AI (Hermes/Atlas)
  → stdio → MCP server Python (FastMCP)
    → HTTP POST → bot_api.php (lib_api_access/*)
      → PHP does the work (auth, DB, WS notify)
    ← JSON response
  ← MCP tool result → AI

Related MCP server: mcp-telegram

Installation

uv pip install -e .

Dependencies: mcp (official SDK), httpx (HTTP client).

Configuration

Copy .env.example to .env and fill in the bot credentials:

cp .env.example .env

Variables:

• AXOMIND_BASE_URL — URL to bot_api.php (e.g. http://xx.xx.xx.xx/app/bot_api.php)

• AXOMIND_BOT_ID — Bot ID (from Axomind UI → bot management)

• AXOMIND_BOT_KEY — Bot access key

• AXOMIND_TIMEOUT — HTTP timeout in seconds (default: 30)

Available tools (14)

Activity / Planning (5)

Mindmap (5)

Simplified format for replace_mindmap / add_nodes

The AI provides a compact JSON — the MCP auto-expands ~25 default fields:

[
  {"title": "Root", "parent": 0, "color": "0xFFF0BA6D", "size_box": 2, "bold": true},
  {"title": "Category A", "parent": 1, "color": "0xFF7A8FF5", "size_box": 1, "line_style": 1},
  {"title": "Item 1", "parent": 2},
  {"title": "Item 2", "parent": 2, "color": "0xFFFF6F91", "free_links": [3]}
]

Fields:

• title (required) — node title

• parent (required) — order_index of the parent node (0 = root, 1 = first node)

• color (optional) — hex color (default: 0xFF7A8FF5)

• pos_x, pos_y (optional) — canvas position (default: 0)

• size_box (optional) — 0=normal, 1=category, 2=root (default: 0)

• bold, italic, underline (optional) — text style

• line_type (optional) — 0=curve, 1=rounded, 2=square

• line_style (optional) — 0=solid, 1=dashed

• stroke_width, dot_radius, radius, border_size, label_size (optional)

• icon_id (optional) — icon ID

• active_bg_colors (optional) — active background colors

• descriptions (optional) — descriptive text

• free_links (optional) — list of order_index for free links between nodes

UID and order_index are assigned automatically. add_nodes reads the existing mindmap and appends after existing nodes.

Messenger (4)

Tests

PYTHONPATH=src python -m pytest tests/ -v

31 tests — mock httpx, no network calls to the Axomind server.

Hermes configuration

In ~/.hermes/config.yaml:

mcp_servers:
  axomind:
    command: "python3"
    args: ["-m", "axomind_mcp.server"]
    env:
      AXOMIND_BASE_URL: "http://xx.xx.xx.xx/app/bot_api.php"
      AXOMIND_BOT_ID: "72"
      AXOMIND_BOT_KEY: "your_key_access"
      PYTHONPATH: "/path/to/axomind-mcp/src"
    workdir: "/path/to/axomind-mcp"

⚠️ All env values must be strings (YAML parses 72 as int → pydantic rejects it). ⚠️ PYTHONPATH is required — workdir sets the cwd but not the Python import path.

Restart Hermes → tools are discovered automatically with the mcp_axomind_ prefix.

Security

• The MCP does not touch the database, read files, or contain any business logic

• Credentials come from environment variables

• The Axomind server cannot tell it's a MCP — it sees normal bot_api requests

• The MCP does not run on production — zero additional attack surface

License

Proprietary — see LICENSE. Copyright © 2025 VEZZANI Sébastien. All rights reserved.