talk-to-girlfriend-ai

talk-to-girlfriend-ai is a Telegram MCP-backed agent that helps you craft witty, engaging messages for conversations. It exposes a rich set of tools for managing chats, reading messages, sending replies, reacting to messages, and performing various AI-assisted actions like transforming messages, searching past chats, and finding relevant dating guidance. The MCP setup connects a Python-based Telegram API bridge with a TypeScript/AI agent, enabling real-time messaging through Telegram and AI-powered suggestions and enhancements. You can interact with the system using natural language queries to read messages, compose replies, search history, and get style-enhanced responses for flirting and conversation starters.

To use it, first configure your Telegram API credentials and AI service keys, then run the Telegram MCP server (as shown in the installation steps). Once running, you can start the bridge and the agent, and use the available MCP tools to read chats, send messages, react, edit, delete, forward messages, and perform Nia-powered semantic searches for pickup lines or dating guides. The available agent tools include core messaging (getChats, getMessages, sendMessage), reactions (sendReaction, replyToMessage), history and search (getHistory, searchMessages), user info (getUserStatus, getUserPhotos), media search (searchGifs), and Nia search tools (searchPickupLines, niaSearch, webSearch), along with AI tools like aiifyMessage for transforming messages into witty responses. Also exposed are 60+ MCP tools providing full Telegram API access such as managing chats, groups, contacts, media, privacy settings, and more.

Prerequisites:

• Python 3.8+ and/or Node.js 14+ depending on your setup
• Access to Telegram API credentials (API ID, API Hash) and a Telegram account
• Access to Nia (trynia.ai) API key and source UUID, and an AI gateway key if using Claude-based workflows

1. Clone the repository and navigate to the project directory:

git clone https://github.com/arlanrakh/talk-to-girlfriend-ai.git
cd talk-to-girlfriend-ai

2. Install and configure the Telegram API bridge (Python):

• Install Python dependencies (as needed by the bridge, e.g., Telethon, FastAPI):

python -m pip install -r requirements.txt

• Generate a session string or ensure you have TELEGRAM_SESSION_STRING ready.

3. Install and configure the AI agent (TypeScript/Bun or Node tooling as used in the repo):

# If agent uses Bun/Node for the AI agent
cd agent
bun install
bun run dev

4. Set up environment variables for the MCP server and AI services:

# Create and edit your environment file (example paths shown in README)
cp .env.example .env

Edit values for TELEGRAM_API_ID, TELEGRAM_API_HASH, TELEGRAM_SESSION_STRING, AI_GATEWAY_API_KEY, NIA_API_KEY, NIA_CODEBASE_SOURCE as appropriate.

5. Start the MCP server (as an MCP you can point to via your config):

• Use the MCP server configuration provided in the next step to run the server with uv.

6. Verify the services are running:

• Ensure the Telegram API bridge (telegram_api.py) is reachable on port 8765
• Ensure the AI agent is serving (e.g., bun dev on the agent folder)

7. Optional: Use the embedded MCP example from the README to integrate into Claude Desktop or Cursor when desired.

Notes and tips:

• Keep your Telegram session data secure; do not commit .env files or session strings to version control.
• The MCP configuration shown uses uv to run the Telegram MCP directory; adjust the --directory path to your actual telegram-mcp directory.
• If you encounter authentication or session string issues, regenerate the session string with uv run session_string_generator.py and restart the bridge.
• This setup runs processing locally; data does not leave your environment beyond Telegram's API calls.
• For troubleshooting, check the mcp_errors.log and make sure both the bridge (telegram_api.py) and the agent (TypeScript/Bun) are running without port conflicts.