iflow-mcp_arlanrakh-talk-to-girlfriend-ai 2.0.1

Telegram integration for Claude via the Model Context Protocol

Telegram AI Dating Agent

p.s: we broke up after this

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.

What It Does

• 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

Powered by Nia

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.

Architecture

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

Quick Start

1. Get Telegram API Credentials

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

2. Install & Configure

# 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

3. Start the Telegram API Bridge

python telegram_api.py

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

4. Run the AI Agent

cd agent
bun install
bun run dev

Usage Examples

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

Agent Commands

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

Environment Variables

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

Alternative: Use as MCP Server

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.

Available Tools

Agent Tools (20+)

Core Messaging

Tool	Description
getChats	List all conversations
getMessages	Read messages from a chat
sendMessage	Send a message
getChat	Get chat details
searchContacts	Search contacts

Reactions & Replies

Tool	Description
sendReaction	React with ❤️ 🔥 😂 etc
replyToMessage	Reply to specific messages

Edit & Delete

Tool	Description
editMessage	Fix typos after sending
deleteMessage	Remove messages

History & Search

Tool	Description
getHistory	Get up to 500 messages
searchMessages	Search chat by text

Forward & Pin

Tool	Description
forwardMessage	Forward to another chat
pinMessage	Pin important messages
markAsRead	Mark messages as read

User Info

Tool	Description
getUserStatus	Check if user is online
getUserPhotos	Get profile photos

Media

Tool	Description
searchGifs	Search for GIFs

Nia Search

Tool	Description
searchPickupLines	Search indexed pickup lines & dating advice
niaSearch	General semantic search
webSearch	Real-time web search

AI Tools

Tool	Description
aiifyMessage	Transform messages into witty responses

MCP Server Tools (60+)

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

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

Troubleshooting

• 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

Security

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

Credits

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

License

Apache 2.0

talk-to-girlfriend-ai