An AI-powered Telegram agent that helps you craft witty, engaging messages for your conversations. Built with Claude Sonnet, Nia semantic search, and a full-featured Telegram MCP integration.

• Smart Reply Suggestions: Get AI-powered response suggestions based on conversation context
• 500+ Pickup Lines: Semantic search through a curated collection of pickup lines indexed with Nia
• Dating Guides: Search through guides on how to talk to women, conversation starters, and flirting tips
• Message Enhancement: Transform boring messages into witty, engaging ones
• Full Telegram Access: Read messages, send replies, manage chats - all through natural language

This agent uses Nia as its knowledge retrieval engine. Nia indexes and searches through:

• 500+ curated pickup lines (funny, cheesy, clever, romantic)
• Guides on conversation techniques
• Tips for keeping conversations engaging

You can index your own content by creating a source at trynia.ai.

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   CLI Agent      │────▶│  Telegram API    │────▶│    Telegram      │
│  (TypeScript)    │     │   Bridge (Py)    │     │    Servers       │
└──────────────────┘     └──────────────────┘     └──────────────────┘
         │
         ▼
┌──────────────────┐     ┌──────────────────┐
│  Claude Sonnet   │     │    Nia API       │
│   (AI Gateway)   │     │ (trynia.ai)      │
└──────────────────┘     └──────────────────┘
                         - 500+ pickup lines
                         - Dating guides
                         - Conversation tips

Get your API credentials at my.telegram.org/apps.

# Clone the repo
git clone https://github.com/arlanrakh/talk-to-girlfriend-ai.git
cd talk-to-girlfriend-ai

# Install Python dependencies
uv sync

# Generate Telegram session string
uv run session_string_generator.py

# Configure environment
cp .env.example .env
# Edit .env with your credentials

python telegram_api.py

This runs a FastAPI server on port 8765 that bridges the TypeScript agent to Telegram.

cd agent
bun install
bun run dev

Once running, interact with natural language:

# Reading & Sending
> Show me messages from @her_username
> Send "Hey, I was just thinking about you" to @her_username
> Reply to her last message with something witty

# Reactions
> React to her last message with ❤️
> Send a 🔥 reaction to message 123

# Search & History
> Search our chat for "dinner plans"
> Show me the last 50 messages with her
> Find me a funny pickup line about pizza

# AI Assistance
> What should I reply to her message about coffee?
> Make this message more flirty: "want to hang out tomorrow?"
> Search for tips on how to keep a conversation going

# User Info
> Is she online right now?
> Check her status

# Message Management
> Edit my last message to fix the typo
> Delete message 456
> Forward that meme to @friend

• /help - Show help
• /clear - Clear conversation history
• /status - Check connection status
• /quit - Exit

Create a .env file in the project root:

# Telegram API (Required)
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_SESSION_STRING=your_session_string

# AI Services (Required for agent)
AI_GATEWAY_API_KEY=your_vercel_ai_gateway_key
NIA_API_KEY=your_nia_api_key
NIA_CODEBASE_SOURCE=your_pickup_lines_source_uuid

You can also use this as a standalone MCP server with Claude Desktop or Cursor, without the AI agent.

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/path/to/telegram-mcp", "run", "main.py"]
    }
  }
}

This exposes 60+ Telegram tools including messaging, contacts, groups, channels, reactions, and more.

Core Messaging

Reactions & Replies

Edit & Delete

History & Search

Forward & Pin

User Info

Media

Nia Search

AI Tools

Full Telegram API access including:

• Chat & Group Management (create, invite, admin, ban)
• Messaging (send, reply, edit, delete, forward, pin, reactions)
• Contact Management (add, search, block, import/export)
• Media & Stickers
• Privacy Settings
• And much more...

docker build -t telegram-mcp:latest .
docker compose up --build

• Database lock errors: Use session string auth instead of file-based
• Auth errors: Regenerate session string with uv run session_string_generator.py
• Connection issues: Check that telegram_api.py is running on port 8765
• Error logs: Check mcp_errors.log for detailed errors

• Never commit your .env or session string
• Session string = full Telegram account access
• All processing is local, data only goes to Telegram API

• Built on telegram-mcp by @chigwell
• Knowledge retrieval powered by Nia
• Uses Telethon, MCP, and Vercel AI SDK

Apache 2.0