danielzotti/mcp-server-telegram-notes

MCP Server Telegram Notes

This project implements a custom MCP Server that allows you to send notes directly to your Telegram account using a Telegram bot. It is designed for quick, programmatic note delivery via the Telegram messaging platform.

What is an MCP Server?

MCP (Model Context Protocol) Server is a server that implements the Model Context Protocol, enabling tools, resources, and prompts to be exposed in a standardized way for AI agents and other clients. MCP Servers can provide custom tools (like sending notes) that can be invoked remotely, making them highly extensible for automation and integration scenarios.

• Model Context Protocol (MCP) documentation

What is a Telegram Bot?

A Telegram bot is a special kind of Telegram account operated by software, not by a human. Bots can interact with users, send and receive messages, and perform automated tasks. Telegram bots are created and managed using the @BotFather bot on Telegram.

• Telegram Bots: Introduction for Developers
• Telegram Bot API Documentation

How to Create a Telegram Bot

1. Open Telegram and search for @BotFather (BotFather documentation).
2. Start a chat and use the /newbot command to create a new bot.
3. Follow the instructions to set a name and username for your bot.
4. After creation, you will receive a Telegram Bot API Token. Save this token; you will need it for configuration.
5. Start a chat with your new bot (search for its username in Telegram and send a message).
6. To get your personal chat ID, you can use tools like userinfobot or send a message to your bot and use the Telegram API to retrieve the chat ID.

Project Folder Structure

├── package.json
├── README.md
├── tsconfig.json
├── .env                # Your environment variables (not committed)
├── src/
│   ├── env.ts          # Loads and validates environment variables
│   └── index.ts        # Main MCP server logic and Telegram integration

How It Works

1. The server is built using the Model Context Protocol SDK and exposes a tool called send-note.
2. When the send-note tool is invoked (remotely or locally), it sends a message to your Telegram account using your bot.
3. The server reads your bot token and chat ID from environment variables, then uses the Telegram Bot API to deliver the message.
4. The project is written in TypeScript and can be run in development mode or built for production.

Setup Instructions

1. Create a .env file in the project root with the following variables:

   • TELEGRAM_TOKEN: Your Telegram bot API token (from @BotFather)
   • TELEGRAM_PERSONAL_CHAT_ID: Your personal chat ID (the identifier for your chat with the bot)

2. Install dependencies:

   npm install
   

3. Run the server in development mode:

   npm run dev
   

4. Build and run for production:

   npm run build
   npm start
   

Environment Variables

Create a .env file and add these variables:

1. TELEGRAM_TOKEN: Telegram bot API Token (use Telegram and @BotFather to retrieve the API token)
2. TELEGRAM_PERSONAL_CHAT_ID: Chat ID (the chat identifier between you and the Telegram bot; overlaps with your user ID)

Setup Instructions to use MCP Server in VSCode

Create a mcp.json file in .vscode folder.

NOTE: dz-telegram-notes-dev is meant to work just for development.

{
	"servers": {
		"dz-telegram-notes-dev": {
			"type": "stdio",
			"command": "npm",
			"args": [
				"run",
				"dev"
			],
			"cwd": "${workspaceFolder}",
			"dev": {
				"watch": "src/**/*.ts",
				"debug": {
					"type": "node"
				}
			}
		},
		"dz-telegram-notes-prod": {
			"type": "stdio",
			"command": "npm",
			"args": [
				"run",
				"start"
			],
			"cwd": "${workspaceFolder}"
		},
	},
}

Setup Instructions for Claude Desktop

Add "mcp-telegram-notes" in claude_desktop_config.json file

{
  "mcpServers": {
	// ...
    "mcp-telegram-notes": {
      "command": "node",
      "args": [
        "PATH_TO_YOUR/dist/index.js"
      ],
      "env": {
        "TELEGRAM_TOKEN": "YourTelegramToken",
        "TELEGRAM_PERSONAL_CHAT_ID": "YourChatId"
      }
    }
	// ...
  },
}