Skip to main content
Glama
Pararam Nexus MCP

Pararam Nexus MCP

Pararam Nexus MCP

A Model Context Protocol (MCP) server for interacting with pararam.io - a modern communication and collaboration platform.

About pararam.io

Pararam.io is a communication platform that provides:

  • Messaging: Create groups and private chats

  • Team Organization: Organize people into teams

  • Communication: Group and private calls (audio and video)

  • Cross-platform: Available on mobile (iOS, Android, Huawei) and web

This MCP server uses the pararamio-aio library to provide asynchronous access to pararam.io features through the Model Context Protocol.

Related MCP server: Telegram MCP Server

Features

  • Asynchronous API client for pararam.io

  • Two-factor authentication support (TOTP)

  • Session persistence with cookie storage

  • Comprehensive chat and message management

  • File attachment handling (upload and download)

  • URL-based message retrieval

  • Conversation thread building

Available Tools

Message Operations

  • search_messages: Search for messages across all chats with advanced search syntax (Boolean operators, wildcards, filters)

  • get_chat_messages: Get recent messages from a specific chat

  • send_message: Send a message to a chat with optional reply and quote text

  • get_message_from_url: Extract and retrieve a message from pararam.io URL

Chat Operations

  • search_chats: Search for chats by name or description

  • build_conversation_thread: Build a conversation tree from a root message

File Operations

  • upload_file_to_chat: Upload files to a chat (from path or base64 content)

  • get_post_attachments: List all attachments in a post

  • download_post_attachment: Download attachments (to disk or as ImageContent)

    • 1MB size limit for downloads

    • Supported formats for direct display: images (JPEG, PNG, GIF, WEBP), documents (PDF, DOCX, DOC, TXT, RTF, ODT, HTML, EPUB), spreadsheets (XLSX, XLS, CSV), data (JSON, XML)

    • Returns ImageContent for supported types (displays natively in Claude Desktop/Code)

    • For unsupported types, requires output_path to save to disk

    • Saves to disk when output path is provided

User Operations

  • search_users: Search for users by name or unique name

  • get_user_info: Get detailed information about a specific user

  • get_user_team_status: Get user's status in teams (member, admin, guest)

Tool Details

send_message

Send a message to a chat with optional reply and quote functionality.

Parameters:

  • chat_id (required): ID of the chat to send message to

  • text (required): Message text to send

  • reply_to_message_id (optional): Post number to reply to

  • quote_text (optional): Text to quote from the replied message (only used with reply_to_message_id)

Message formatting: Pararam supports Markdown-like text, but does not support Markdown headings (#, ##, ###). Use **bold** section titles instead. Use colors as [#RRGGBB](text); colored bullet example: [#2E7D32](●). Keep tables simple because colors may not render inside table cells. Use @all, @online, @admin, and @groups only when the user explicitly asks for broad notification, and ask for explicit confirmation before sending such mentions. See docs/PARARAM_FORMATTING.md for the full syntax.

Examples:

# Simple message
send_message(chat_id="123", text="Hello!")

# Reply to a message
send_message(
    chat_id="123",
    text="I agree!",
    reply_to_message_id="456"
)

# Reply with quoted text
send_message(
    chat_id="123",
    text="That's a great idea!",
    reply_to_message_id="456",
    quote_text="We should implement this feature next week"
)

Installation

Use the published PyPI package by default:

uvx pararam-nexus-mcp

For unreleased development snapshots, you can run directly from GitHub:

uvx --from git+https://github.com/ivolnistov/pararam-nexus-mcp pararam-nexus-mcp

For local development, clone the repository and install dependencies:

git clone https://github.com/ivolnistov/pararam-nexus-mcp.git ~/.mcp/pararam-nexus-mcp
cd ~/.mcp/pararam-nexus-mcp
uv sync

Docker Installation

Pull from Docker Hub:

docker pull ivolnistov/pararam-nexus-mcp:latest

Or from GitHub Container Registry:

docker pull ghcr.io/ivolnistov/pararam-nexus-mcp:latest

Development Installation

For local development:

git clone https://github.com/ivolnistov/pararam-nexus-mcp.git
cd pararam-nexus-mcp
uv sync --dev

Configuration

The server runs in one of two modes depending on which env vars are set.

Full mode — login + password (+ optional 2FA)

All tools are registered. Cookies are persisted between runs.

PARARAM_LOGIN=your_login
PARARAM_PASSWORD=your_password
PARARAM_2FA_KEY=your_2fa_key  # optional

Limited mode — X-UserToken service token

Set PARARAM_USER_TOKEN (mutually exclusive with PARARAM_LOGIN/PARARAM_PASSWORD). Only the chat / message / post / replies / edit / delete tools are registered; user lookups, global search, and file ops are excluded.

PARARAM_USER_TOKEN=your_service_token

To get a service token in Pararam:

  1. Open the Pararam Info Chat bot documentation.

  2. In User Tokens, run Create new token (bot://cmd_create_user_token?title=Create+new+token&conf=True).

  3. InfoBot will reply with New user token - ....

  4. Copy that value into PARARAM_USER_TOKEN and store it as a secret.

Tools available in limited mode:

  • Chats — get_chat, create_private_chat, create_group_chat, create_thread_chat

  • Posts — get_chat_messages, get_message_from_url, get_reply_thread, get_replies_to_post, send_message, edit_post, delete_post

MCP Client Configuration

Claude Code (CLI)

Add the server using the Claude Code CLI:

# Using uvx (recommended)
claude mcp add pararam-nexus \
  --env PARARAM_LOGIN=myuser@example.com \
  --env PARARAM_PASSWORD=mySecurePassword123 \
  --env PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP \
  -- uvx pararam-nexus-mcp

# Using Docker
claude mcp add pararam-nexus \
  --env PARARAM_LOGIN=myuser@example.com \
  --env PARARAM_PASSWORD=mySecurePassword123 \
  --env PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP \
  -- docker run -i --rm ivolnistov/pararam-nexus-mcp:latest

Claude Desktop

  1. Open Claude Desktop preferences

  2. Navigate to the MCP section

  3. Click Edit to open claude_desktop_config.json

  4. Add the server configuration:

{
  "mcpServers": {
    "pararam-nexus": {
      "command": "uvx",
      "args": ["pararam-nexus-mcp"],
      "env": {
        "PARARAM_LOGIN": "myuser@example.com",
        "PARARAM_PASSWORD": "mySecurePassword123",
        "PARARAM_2FA_KEY": "JBSWY3DPEHPK3PXP"
      }
    }
  }
}

Option 2: Using Docker

First, create a volume for session persistence:

docker volume create pararam-mcp-data

Then add to claude_desktop_config.json:

{
  "mcpServers": {
    "pararam-nexus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "pararam-mcp-data:/app/.cookies",
        "-e",
        "PARARAM_LOGIN=myuser@example.com",
        "-e",
        "PARARAM_PASSWORD=mySecurePassword123",
        "-e",
        "PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP",
        "ivolnistov/pararam-nexus-mcp:latest"
      ]
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pararam-nexus": {
      "command": "uvx",
      "args": ["pararam-nexus-mcp"],
      "env": {
        "PARARAM_LOGIN": "myuser@example.com",
        "PARARAM_PASSWORD": "mySecurePassword123",
        "PARARAM_2FA_KEY": "JBSWY3DPEHPK3PXP"
      }
    }
  }
}

Or using Docker (with session persistence):

First, create a volume:

docker volume create pararam-mcp-data

Then add to .cursor/mcp.json:

{
  "mcpServers": {
    "pararam-nexus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "pararam-mcp-data:/app/.cookies",
        "-e",
        "PARARAM_LOGIN=myuser@example.com",
        "-e",
        "PARARAM_PASSWORD=mySecurePassword123",
        "-e",
        "PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP",
        "ivolnistov/pararam-nexus-mcp:latest"
      ]
    }
  }
}

Other MCP-Compatible Clients

For any MCP-compatible client that supports stdio transport:

Using uvx:

uvx pararam-nexus-mcp

Using Docker (with session persistence):

# Create volume for cookies
docker volume create pararam-mcp-data

# Run with volume mounted
docker run -i --rm \
  -v pararam-mcp-data:/app/.cookies \
  -e PARARAM_LOGIN=myuser@example.com \
  -e PARARAM_PASSWORD=mySecurePassword123 \
  -e PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP \
  ivolnistov/pararam-nexus-mcp:latest

Environment variables:

  • PARARAM_LOGIN (full mode): Your pararam.io login

  • PARARAM_PASSWORD (full mode): Your pararam.io password

  • PARARAM_2FA_KEY (optional): Your 2FA secret key for TOTP authentication in full mode

  • PARARAM_USER_TOKEN (limited mode): Service token sent as X-UserToken

Set either PARARAM_LOGIN/PARARAM_PASSWORD or PARARAM_USER_TOKEN, not both.

Usage

If installed with uvx:

uvx pararam-nexus-mcp

If cloned locally:

cd ~/.mcp/pararam-nexus-mcp
uv run pararam-nexus-mcp

For development:

uv run pararam-nexus-mcp

Development

Install pre-commit hooks:

uv run pre-commit install

Run linting and formatting:

uv run ruff check --fix src/
uv run ruff format src/

Run type checking:

uv run mypy src/pararam_nexus_mcp

Run tests:

uv run pytest

Dependencies

  • FastMCP: Model Context Protocol server framework

  • pararamio-aio: Async Python client for pararam.io API

  • httpx: Modern HTTP client

  • Pydantic: Data validation using Python type annotations

License

MIT

Available Tools

20 tools
build_conversation_threadA

Build a conversation thread starting from a root message.

Returns all messages that are replies to the root message or replies to those replies, recursively.

Args: chat_id: ID of the chat root_message_id: Post number to use as root of the conversation limit: Maximum number of recent messages to load and search (default: 100)

Returns: ToolResponse with BuildConversationThreadPayload containing flat list of all posts in the thread, sorted by post_no. Each post contains reply_to_post_no to reconstruct the tree structure.

Inputs: chat_id (required), root_message_id (required), limit. Returns: error, message, payload, success

create_group_chatA

Create a group chat with the given title and member set.

Args: title: Group chat title (required). description: Optional chat description. users: List of user IDs to invite. Empty/None creates an empty chat. organization_id: Organization to scope the chat to (optional).

Returns: ToolResponse with the new chat's ID and title.

Inputs: title (required), users, description, organization_id. Returns: error, message, payload, success

create_private_chatA

Create a personal (PM) chat with another user.

Args: user_id: Numeric ID of the user to start a PM with.

Returns: ToolResponse with the new chat's ID.

Inputs: user_id (required). Returns: error, message, payload, success

create_thread_chatA

Create a branch (thread) chat rooted at a specific post in another chat.

Requires the parent chat to have allow_branch=True. Errors otherwise.

Args: parent_chat_id: ID of the chat to branch from. post_no: Post number to root the branch at. title: Optional title for the branch chat.

Returns: ToolResponse with the new branch chat's ID.

Inputs: post_no (required), parent_chat_id (required), title. Returns: error, message, payload, success

delete_postA

Delete a post.

Args: chat_id: Numeric chat ID. post_no: Post number to delete (must be authored by the token's user).

Returns: ToolResponse confirming the delete and the resulting is_deleted flag.

Inputs: chat_id (required), post_no (required). Returns: error, message, payload, success

download_post_attachmentA

Download a specific attachment from a post.

If output_path is provided, saves file to disk and returns DownloadAttachmentResponse. If output_path is None and file type is supported, returns ImageContent for direct display. If output_path is None and file type is not supported, returns DownloadAttachmentErrorResponse.

Supported file types for ImageContent:

  • Images: JPEG, PNG, GIF, WEBP

  • Documents: PDF, DOCX, DOC, TXT, RTF, ODT, HTML, EPUB

  • Spreadsheets: XLSX, XLS, CSV

  • Data: JSON, XML

Args: chat_id: ID of the chat post_no: Post number file_guid: GUID of the file to download (from get_post_attachments) output_path: Optional absolute path where to save the file. If None, only supported file types can be displayed

Returns: ImageContent for supported file types (direct display in Claude), DownloadAttachmentResponse model when saved to disk, DownloadAttachmentErrorResponse model for errors, or error string

Inputs: chat_id (required), post_no (required), file_guid (required), output_path.

edit_postA

Edit an existing post.

Args: chat_id: Numeric chat ID. post_no: Post number to edit (must be authored by the token's user). text: New post text. quote: Optional quoted text override. reply_no: Optional change to which post this one replies to.

Returns: ToolResponse with the edited post's identity and new text.

Inputs: text (required), chat_id (required), post_no (required), quote, +1 more. Returns: error, message, payload, success

get_chatA

Fetch a single chat's metadata by ID.

Args: chat_id: Numeric chat ID.

Returns: ToolResponse with the chat title, type, member counts, and description.

Inputs: chat_id (required). Returns: error, message, payload, success

get_chat_messagesA

Get messages from a specific chat.

Args: chat_id: ID of the chat to get messages from limit: Maximum number of messages to return (default: 50) before_message_id: Get messages before this message ID (for pagination). If provided, returns messages older than this ID.

Returns: ToolResponse with GetChatMessagesPayload containing chat messages including sender, text, and timestamp

Inputs: chat_id (required), limit, before_message_id. Returns: error, message, payload, success

get_message_from_urlA

Get a specific message from a pararam.io URL.

Args: url: Pararam.io URL (e.g., https://app.pararam.io/#/organizations/1/threads/12345#post_no-6789)

Returns: ToolResponse with GetMessageFromUrlPayload containing message details including post_no, text, sender, and timestamp

Inputs: url (required). Returns: error, message, payload, success

get_post_attachmentsA

Get list of attachments (files, images, documents) from a specific post.

Args: chat_id: ID of the chat post_no: Post number

Returns: ToolResponse with GetPostAttachmentsPayload containing list of attachments including file ID, name, size, and download URL

Inputs: chat_id (required), post_no (required). Returns: error, message, payload, success

get_replies_to_postA

Fetch direct replies to a post (one level deep, hydrated).

Args: chat_id: Numeric chat ID. post_no: Post number whose direct replies should be returned.

Returns: ToolResponse with PostInfo entries for each direct reply.

Inputs: chat_id (required), post_no (required). Returns: error, message, payload, success

get_reply_threadA

Fetch the full reply thread rooted at a post (server-side rerere traversal).

Returns every post number in the thread in the order the server reports them — the root and every transitively-reachable reply.

Args: chat_id: Numeric chat ID. post_no: Post number to root the thread traversal at.

Returns: ToolResponse with the list of post numbers comprising the thread.

Inputs: chat_id (required), post_no (required). Returns: error, message, payload, success

get_user_infoC

Get detailed information about a specific user.

Args: user_id: User ID

Returns: ToolResponse with GetUserInfoPayload containing user details including id, name, unique_name, and team memberships

Inputs: user_id (required). Returns: error, message, payload, success

get_user_team_statusA

Get user's status in teams (member, admin, guest, or not in team).

Args: user_id: User ID to check team_id: Optional team ID to check status in specific team. If not provided, returns status in all teams.

Returns: ToolResponse with GetUserTeamStatusPayload containing team membership status including is_member, is_admin, is_guest, and state

Inputs: user_id (required), team_id. Returns: error, message, payload, success

search_chatsA

Search for chats by name or description.

Args: query: Search query string limit: Maximum number of results to return (default: 20, applied client-side)

Returns: ToolResponse with SearchChatsPayload containing chat list including chat ID, name, type, and member count

Inputs: query (required), limit. Returns: error, message, payload, success

search_messagesA

Search for messages across all chats or in specific chats.

Args: query: Search query string. Supports search filters (see below) limit: Maximum number of results to return (default: 20) chat_ids: Optional list of chat IDs to search within. If None, search in all chats.

Search Syntax: Boolean Operators: By default, all terms are optional (OR), as long as one term matches. Search for "foo bar baz" finds any document containing foo OR bar OR baz.

    + (must be present) - Example: +fox (fox must be found)
    - (must not be present) - Example: -news (news must be excluded)
    Example: "quick brown +fox -news" (fox required, news excluded, quick/brown optional)

    AND, OR, NOT (also &&, ||, !) - Standard boolean operators
    NOTE: NOT takes precedence over AND, which takes precedence over OR
    Example: "(quick OR brown) AND fox"

Grouping:
    Use parentheses to group terms: "(quick OR brown) AND fox"

Wildcards:
    ? - Replace single character: "qu?ck"
    * - Replace zero or more characters: "bro*"

Strict Search:
    Use quotes for exact phrase match: "some search phrase"

Fuzziness:
    Use ~ for similar terms (Damerau-Levenshtein distance, max 2 changes):
    "quikc~ brwn~ foks~" or "quikc~1" (edit distance of 1)

Proximity Search:
    Use ~N after phrase to allow words to be N positions apart:
    "fox quick"~5 (allows up to 5 words distance, any order)

Search Filters: Format: search text /filter1 param1 param2 /filter2 param

/users or /from - Find posts by specific users
    Example: /users @user1 @user2 or /from @user1 @user2

/replyto or /reply - Find messages that are replies to specified users
    Example: /replyto @user1 @user2 or /reply @user1 @user2

/to - Find messages that mention users OR are replies to them
    Example: /to @user1 @user2

/file - Find files by name pattern
    Example: /file *filen?me*

/from_date or /after - Find posts created after a date (YYYY-MM-DD, YYYY-MM, or YYYY)
    Example: /from_date 2016-01-22 or /after 2016-01 or /after 2016

/to_date or /before - Find posts created before a date (YYYY-MM-DD, YYYY-MM, or YYYY)
    Example: /to_date 2016-01-22 or /before 2016-01 or /before 2016

/tags - Find posts containing specific tags (strict match)
    Example: /tags hey may day or /tags #hey #may #day or #hey #may #day

/has - Find posts based on content type:
    /has tag - Posts containing tags (e.g., #may)
    /has link - Posts containing URLs or markdown links
    /has email - Posts containing email addresses
    /has mention - Posts mentioning any user or user with role
    /has user - Posts containing user mentions or words starting with @
    /has group - Posts containing role mentions
    /has reply - Posts that are replies
    /has file - Posts with attached files
    /has block - Posts with text in blocks (>text or ```text)
    /has poll - Posts containing polls

Returns: ToolResponse with SearchMessagesPayload containing search results with message text, sender, chat info, and timestamp

Inputs: query (required), limit, chat_ids. Returns: error, message, payload, success

search_usersA

Search for users by name or unique name.

Args: query: Search query string (name or unique_name) limit: Maximum number of results to return (default: 20)

Returns: ToolResponse with SearchUsersPayload containing list of users including id, name, unique_name, and team memberships

Inputs: query (required), limit. Returns: error, message, payload, success

send_messageA

Send a message to a chat.

Args: chat_id: ID of the chat to send message to text: Message text to send reply_to_message_id: Post number to reply to (optional) quote_text: Text to quote from the replied message (optional, only used with reply_to_message_id)

Returns: ToolResponse with SendMessagePayload containing sent message details including message ID and timestamp

Inputs: text (required), chat_id (required), quote_text, reply_to_message_id. Returns: error, message, payload, success

upload_file_to_chatA

Upload a file to a chat.

Args: chat_id: ID of the chat to upload file to file_path: Absolute path to the file on local filesystem (mutually exclusive with file_content) file_content: Base64-encoded file content (mutually exclusive with file_path) filename: Filename to use when file_content is provided (required if file_content is set) reply_to_message_id: Post number to reply to (optional)

Returns: ToolResponse with UploadFilePayload containing uploaded file details including file ID, name, size, and URL

Inputs: chat_id (required), filename, file_path, file_content, +1 more. Returns: error, message, payload, success

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 20 tools

    Disambiguation4/5

    Tools are mostly distinct, but build_conversation_thread and get_reply_thread both retrieve threads with different methods, potentially causing confusion. Other overlaps are minor and clarified by descriptions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., create_group_chat, get_chat_messages). No mixing of conventions, making the surface predictable.

    Tool Count5/5

    20 tools is well-scoped for a messaging platform, covering creation, retrieval, editing, search, and file handling without unnecessary redundancy.

    Completeness4/5

    Core messaging workflows are covered, but missing update/delete chat, member management, and chat listing. Minor gaps that agents can work around.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Rocket.Chat instances through MCP protocol. Allows users to manage chat operations and integrate with Rocket.Chat servers using natural language commands.
      6
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with Telegram chat history, including text, photos, and documents, via the GramJS MTProto userbot. It provides tools for searching chats, syncing message history, and downloading media files for local analysis.
      7
      35 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to interact with Telegram, including listing chats, reading messages, sending messages, searching, and managing contacts.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
      2
      MIT