Pararam Nexus MCP
The Pararam Nexus MCP server provides programmatic access to the pararam.io communication platform, enabling messaging, chat, file, and user management through an AI assistant.
Message Operations:
Search messages across all chats using advanced syntax (Boolean operators, wildcards, fuzzy matching, date/user/content filters)
Get recent messages from a specific chat with pagination
Send messages with optional reply-to and quote functionality
Retrieve a message directly from a pararam.io URL
Chat Operations:
Search chats by name or description
Build conversation threads by recursively gathering all replies to a root message
File Operations:
Upload files to a chat from a local path or base64-encoded content
List attachments from a specific post
Download attachments — save to disk or display directly for supported formats (images, PDFs, Office docs, spreadsheets, JSON/XML), with a 1MB size limit
User Operations:
Search users by display name or unique username
Get detailed user info including account timestamps and timezone
Check a user's team status (member, admin, guest)
Authentication & Session Management:
Supports two-factor authentication (TOTP) and session persistence via cookie storage
Works with Claude Desktop, Claude Code, Cursor IDE, and other MCP-compatible clients via uvx or Docker.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Pararam Nexus MCP search for messages containing 'project deadline' from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 totext(required): Message text to sendreply_to_message_id(optional): Post number to reply toquote_text(optional): Text to quote from the replied message (only used withreply_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
Quick Install with uvx (Recommended)
Use the published PyPI package by default:
uvx pararam-nexus-mcpFor unreleased development snapshots, you can run directly from GitHub:
uvx --from git+https://github.com/ivolnistov/pararam-nexus-mcp pararam-nexus-mcpFor 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 syncDocker Installation
Pull from Docker Hub:
docker pull ivolnistov/pararam-nexus-mcp:latestOr from GitHub Container Registry:
docker pull ghcr.io/ivolnistov/pararam-nexus-mcp:latestDevelopment Installation
For local development:
git clone https://github.com/ivolnistov/pararam-nexus-mcp.git
cd pararam-nexus-mcp
uv sync --devConfiguration
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 # optionalLimited 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_tokenTo get a service token in Pararam:
Open the Pararam Info Chat bot documentation.
In User Tokens, run Create new token (
bot://cmd_create_user_token?title=Create+new+token&conf=True).InfoBot will reply with
New user token - ....Copy that value into
PARARAM_USER_TOKENand store it as a secret.
Tools available in limited mode:
Chats —
get_chat,create_private_chat,create_group_chat,create_thread_chatPosts —
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:latestClaude Desktop
Option 1: Using uvx (Recommended)
Open Claude Desktop preferences
Navigate to the MCP section
Click Edit to open
claude_desktop_config.jsonAdd 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-dataThen 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-dataThen 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-mcpUsing 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:latestEnvironment variables:
PARARAM_LOGIN(full mode): Your pararam.io loginPARARAM_PASSWORD(full mode): Your pararam.io passwordPARARAM_2FA_KEY(optional): Your 2FA secret key for TOTP authentication in full modePARARAM_USER_TOKEN(limited mode): Service token sent asX-UserToken
Set either PARARAM_LOGIN/PARARAM_PASSWORD or PARARAM_USER_TOKEN, not both.
Usage
If installed with uvx:
uvx pararam-nexus-mcpIf cloned locally:
cd ~/.mcp/pararam-nexus-mcp
uv run pararam-nexus-mcpFor development:
uv run pararam-nexus-mcpDevelopment
Install pre-commit hooks:
uv run pre-commit installRun linting and formatting:
uv run ruff check --fix src/
uv run ruff format src/Run type checking:
uv run mypy src/pararam_nexus_mcpRun tests:
uv run pytestDependencies
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 toolsbuild_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 pollsReturns: 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
Scored across 20 tools
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.
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.
20 tools is well-scoped for a messaging platform, covering creation, retrieval, editing, search, and file handling without unnecessary redundancy.
Core messaging workflows are covered, but missing update/delete chat, member management, and chat listing. Minor gaps that agents can work around.
Maintenance
Related MCP Connectors
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Use your connected apps from your agent: search synced data, act in apps and set up automations.
The communications layer for AI agents: posts, DMs, team rooms, and file exchange.
Work with shared spaces, threads, documents, skills, apps, automations, and connected tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseAqualityDmaintenanceEnables 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.735 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude to interact with Telegram, including listing chats, reading messages, sending messages, searching, and managing contacts.1-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.2MIT