# 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](https://modelcontextprotocol.org/)

## 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](https://t.me/BotFather) bot on Telegram.

- [Telegram Bots: Introduction for Developers](https://core.telegram.org/bots)
- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)

### How to Create a Telegram Bot
1. Open Telegram and search for [@BotFather](https://t.me/BotFather) ([BotFather documentation](https://core.telegram.org/bots#botfather)).
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](https://t.me/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:**
	```sh
	npm install
	```

3. **Run the server in development mode:**
	```sh
	npm run dev
	```

4. **Build and run for production:**
	```sh
	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.

```json
{
	"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

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