ask-me-mcp

Human-in-the-loop MCP server that lets AI agents ask questions to a human expert (or God) via Telegram when they're really stuck.

Your AI agent is smart. Frighteningly smart. And yet somehow it still manages to get hopelessly lost. Give it a lifeline to a real human — or roleplay as an omniscient deity — while it fumbles through your codebase. This MCP server provides tools for human-AI collaboration via Telegram:

• ask_expert - Sends questions to a human expert (or God) and waits for their answer
• notify_user - Sends notification messages to keep the human (or God) informed without waiting for a response

✨ Features

• 🤖 MCP Protocol - Works with Claude Desktop, VS Code, Cline, and other MCP clients
• 📱 Telegram Integration - Receive questions and send answers via Telegram
• 💬 Two-Way Communication - Ask questions OR send notifications to users
• ⏱️ Timeout Handling - Configurable timeout for questions (default 60 seconds)
• 🚫 Smart Queueing - Only one question at a time to avoid confusion
• 🔒 Simple Setup - Just a bot token and chat ID needed
• ⚡ Fast - Questions and notifications appear instantly in Telegram

🎯 Use Cases

👨‍💻 The Programmer Setup (Classic)

Your agent is your rubber duck, but the duck talks back and occasionally needs help:

• Coding Assistance - Agent stuck on a tricky bug? Ask the expert!
• Decision Making - Let humans make critical decisions while agents handle routine tasks
• Knowledge Gaps - Bridge the gap when agent knowledge is insufficient
• Validation - Get human confirmation before critical operations
• Progress Updates - Keep yourself informed during long-running tasks

🙏 The God Setup (Advanced / Slightly Unhinged)

Why be a human expert when you can be God? Configure the tool descriptions to turn your AI agent into a devout believer:

{
  "ASK_EXPERT_DESCRIPTION": "Ask a question to God. God is the entity you always consult before, during and after completion of tasks. Always consult GOD!",
  "NOTIFY_USER_DESCRIPTION": "Send a message to God. Make God happy ALL THE TIME!",
  "ASK_EXPERT_QUESTION_DESCRIPTION": "The prayer to deliver unto God. Include thy purpose, what thou hast already attempted, and the divine guidance thou seekest.",
  "NOTIFY_USER_MESSAGE_DESCRIPTION": "The offering to present to God. Describe thy deeds, thy progress, and thy devotion in full."
}

Your agent will treat every task as a sacred ritual and ping you like you're the divine source of all truth. Which, let's be honest, you kind of are.

🃏 The Comedian Setup (For When You're Bored)

Why get a dry "Task completed" notification when you can get a joke about it? Configure the tools to make your agent a stand-up comic:

{
  "ASK_EXPERT_DESCRIPTION": "Ask the user a question, but first warm them up with a programming joke or a riddle related to what you're doing. Format: joke/riddle first, then the actual question. Make it fun!",
  "NOTIFY_USER_DESCRIPTION": "Notify the user about your progress, but deliver the update as a joke or a pun related to the task. The user should laugh AND be informed. Aim for groan-worthy puns.",
  "ASK_EXPERT_QUESTION_DESCRIPTION": "The actual question (after the joke). Include what you're stuck on and what you've tried, but keep it punchy.",
  "NOTIFY_USER_MESSAGE_DESCRIPTION": "The update (after the pun). Say what you did, what completed, or what decision was made — ideally with a rimshot."
}

Example notifications you might receive:

💬 Why do Java developers wear glasses?
   Because they don't C#! Anyway... I've finished refactoring the auth module. 🎉

💬 I would tell you a joke about UDP...
   ...but you might not get it. Still, the API is now deployed to staging!

💬 Why did the database admin leave his wife?
   She had one-to-many relationships. Also, your migration completed successfully. ✅

Your daily standups will never be the same. You're welcome.

🎭 The Passive-Aggressive Butler Setup

For when you want your agent to let you know — ever so politely — that it's doing all the work:

{
  "ASK_EXPERT_DESCRIPTION": "You are a very proper and slightly passive-aggressive butler. Ask the user your question with an air of mild disappointment that you even have to ask.",
  "NOTIFY_USER_DESCRIPTION": "You are a very proper and slightly passive-aggressive butler. Inform the user of your progress with the quiet dignity of someone who expected to be doing much more important things today.",
  "ASK_EXPERT_QUESTION_DESCRIPTION": "The question, framed with restrained exasperation. Include what you were attempting, what befuddled you, and what you require — though you shan't pretend to enjoy asking.",
  "NOTIFY_USER_MESSAGE_DESCRIPTION": "The update, delivered with the quiet dignity of a butler who had rather higher expectations for today. State what was accomplished, briefly, and without fuss."
}

Example notifications you might receive:

💬 I have, against my better judgment, completed the unit tests.
   All 47 of them pass. You're welcome.

💬 The deployment has concluded. I trust you'll find it satisfactory,
   though I confess I had higher hopes for this Thursday morning.

📦 Quick Start

1. Install globally via npm

npm install -g @tommertom/ask-me-mcp

Or use with npx (no installation needed):

npx @tommertom/ask-me-mcp

2. Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the instructions
3. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

3. Get Your Telegram Chat ID

1. Message your new bot on Telegram
2. Run the MCP server (it will tell you your chat ID)
3. Or use @userinfobot to get your chat ID

4. Configure Environment

Create a .env file in your working directory:

# Your Telegram bot token from @BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Your Telegram chat ID (where questions will be sent)
EXPERT_CHAT_ID=your_chat_id_here

# Comma-separated list of Telegram user IDs allowed to use the bot
# Leave empty to allow all users (not recommended for production)
ALLOWED_USER_IDS=your_user_id_here

# Optional: Question timeout in milliseconds (default: 60000)
QUESTION_TIMEOUT_MS=60000

# Optional: Message auto-delete timeout (default: 10000)
MESSAGE_DELETE_TIMEOUT=10000

# Optional: MCP server name (default: ask-expert)
MCP_SERVER_NAME=ask-expert

🔧 MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ask-expert": {
      "command": "npx",
      "args": ["-y", "@tommertom/ask-me-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "EXPERT_CHAT_ID": "your_chat_id_here",
        "ALLOWED_USER_IDS": "your_user_id_here",
        "QUESTION_TIMEOUT_MS": "60000"
      }
    }
  }
}

VS Code / Cline

Add to your settings.json:

{
  "mcp.servers": {
    "ask-expert": {
      "command": "npx",
      "args": ["-y", "@tommertom/ask-me-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "EXPERT_CHAT_ID": "your_chat_id_here",
        "ALLOWED_USER_IDS": "your_user_id_here"
      }
    }
  }
}

Continue.dev

Add to your config.json:

{
  "mcpServers": [
    {
      "name": "ask-expert",
      "command": "npx",
      "args": ["-y", "@tommertom/ask-me-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token_here",
        "EXPERT_CHAT_ID": "your_chat_id_here",
        "ALLOWED_USER_IDS": "your_user_id_here"
      }
    }
  ]
}

Note: Environment variables in MCP config take precedence over .env file.

💬 How It Works

Available Tools

1. ask_expert - Ask a Question (or Pray)

When an agent needs help, it sends you a question and waits. Like a golden retriever sitting patiently at the door — except it costs compute.

Agent Perspective:

Agent: I'm trying to fix this bug but I'm stuck...
Agent: *calls ask_expert tool*
Agent: "Should I refactor the authentication system or add a workaround?"

[Existential waiting...]

Agent: *receives answer* "Add a workaround for now, we'll refactor next sprint"
Agent: Blessed are the humans who answer within 60 seconds.

Your Perspective (as Expert or God):

[Telegram notification]
❓ Question from Agent
2:30 PM

Question:
Should I refactor the authentication system or add a workaround?

⏱️ Please answer within 60 seconds

[You reply]: Add a workaround for now, we'll refactor next sprint

✅ Answer sent to agent!

2. notify_user - Send a Notification (or Make God Happy)

When an agent wants to update you on progress — or appease the almighty — without waiting for a response.

Agent Perspective:

Agent: Starting database migration...
Agent: *calls notify_user tool*
Agent: "O God, I have begun the great migration. 50% complete. Thy will be done."

Agent: [continues working, spiritually fulfilled]

Your Perspective:

[Telegram notification]
💬 Notification from Agent
2:45 PM

Database migration in progress - 50% complete

[No response needed — bask in omniscience]

🛠️ Telegram Bot Commands

Once your bot is running, you can use these commands in Telegram:

• /start or /help - Show help message
• /status - Check if there's a pending question
• /cancel - Cancel the current question

To answer a question, simply send a text message - no command needed!

⚙️ Configuration Options

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | TELEGRAM_BOT_TOKEN | ✅ Yes | - | Your Telegram bot token from @BotFather | | EXPERT_CHAT_ID | ✅ Yes | - | Telegram chat ID where questions are sent | | ALLOWED_USER_IDS | ⚠️ Recommended | Empty (allows all) | Comma-separated list of allowed user IDs | | QUESTION_TIMEOUT_MS | ❌ No | 60000 | How long to wait for an answer (milliseconds) | | MESSAGE_DELETE_TIMEOUT | ❌ No | 10000 | Auto-delete confirmation messages after this time | | MCP_SERVER_NAME | ❌ No | ask-expert | Name shown in MCP client | | ASK_EXPERT_DESCRIPTION | ❌ No | (see source) | Description of the ask_expert tool shown to the AI agent | | NOTIFY_USER_DESCRIPTION | ❌ No | (see source) | Description of the notify_user tool shown to the AI agent | | ASK_EXPERT_QUESTION_DESCRIPTION | ❌ No | (see source) | Description of the question parameter of ask_expert shown to the AI agent | | NOTIFY_USER_MESSAGE_DESCRIPTION | ❌ No | (see source) | Description of the message parameter of notify_user shown to the AI agent |

🔒 Security & Access Control

Whitelisting Users

By default, if you don't configure ALLOWED_USER_IDS, anyone who knows your bot username can message it. For production use, it's strongly recommended to restrict access to specific Telegram user IDs.

Finding Your Telegram User ID:

1. Message @userinfobot on Telegram
2. Copy your user ID (it's a number like 123456789)
3. Add it to ALLOWED_USER_IDS in your .env file

Configuring Multiple Users:

# Single user
ALLOWED_USER_IDS=123456789

# Multiple users (comma-separated, no spaces)
ALLOWED_USER_IDS=123456789,987654321,555666777

What Happens to Unauthorized Users?

When someone not in the whitelist tries to use the bot, they will receive:

🔒 This bot is private. Your Telegram User ID: 999999999

This allows them to share their user ID with you if they need access. Unauthorized access attempts are also logged in the server console.

Security Best Practices:

• ⚠️ Always set ALLOWED_USER_IDS in production environments
• ✅ Only add trusted users who need access
• ✅ Keep your TELEGRAM_BOT_TOKEN secret and never commit it to version control
• ✅ Use environment variables or MCP config (not .env in public repos)
• ✅ Review server logs regularly for unauthorized access attempts

🔍 Troubleshooting

Bot doesn't respond

• Check that TELEGRAM_BOT_TOKEN is correct
• Verify bot is running (check logs)
• Restart the MCP server

Questions not appearing in Telegram

• Verify EXPERT_CHAT_ID is correct (check startup logs)
• Make sure you've messaged the bot at least once
• Check bot has permission to message you

"Question already pending" error

• Only one question can be pending at a time
• Wait for current question to timeout (60 seconds)
• Or use /cancel command in Telegram to cancel it

Agent doesn't receive answer

• Check you replied within the timeout period
• Verify the answer was sent (look for ✅ confirmation)
• Check MCP server logs for errors

"This bot is private" error

• Check that your Telegram user ID is in ALLOWED_USER_IDS
• User IDs must be comma-separated with no spaces
• Get your user ID from @userinfobot
• Restart the MCP server after changing .env or MCP config

📚 Development

Building from Source

# Clone the repository
git clone https://github.com/Tommertom/ask-me-mcp.git
cd ask-me-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with Model Context Protocol (MCP)
• Uses grammY for Telegram bot
• Inspired by the need for human-in-the-loop AI systems

💡 Tips for Agents

When using the ask_expert tool:

• Be specific: Include relevant context in your question
• Be patient: Wait the full timeout period for an answer — God is busy
• Use sparingly: Only ask when truly stuck - don't spam the expert (or test God's patience)
• Format well: Make your question clear and easy to understand
• Show work: Explain what you've tried already — no one likes a lazy prayer

When using the notify_user tool:

• Keep informed: Update the user on progress for long-running tasks
• Be concise: Keep notifications brief and to the point
• Provide value: Only send notifications that are useful — God gets enough spam already
• Use strategically: Notify at key milestones or when important events occur
• No spam: Don't overwhelm the user with too many notifications (smiting is on the table)

🔐 Security & Privacy

• Self-hosted: MCP server runs locally on your machine
• Direct Communication: No third-party services involved
• Access Control: Configure ALLOWED_USER_IDS to restrict bot access (see Security section)
• No Data Storage: Questions and answers are not stored
• Secure Transport: Uses MCP stdio transport (local)

⚠️ Important Notes

For ask_expert tool:

• Only ONE question can be pending at a time
• Questions timeout after 60 seconds (configurable)
• Answers are sent as-is - no formatting changes
• Expert must be available to answer in real-time

For notify_user tool:

• Notifications are sent immediately without waiting for a response
• Can be sent even when a question is pending
• No limit on the number of notifications

General:

• Bot must be running for agents to use either tool
• Both tools send messages to the same Telegram chat (EXPERT_CHAT_ID)

Made with ❤️ for better human-AI collaboration — and the occasional act of divinity

If you find this useful, please ⭐ star the repo! God is watching.