spring-ai-openai-telegram-agent

devsahamerlin/spring-ai-openai-telegram-agent

3.1

If you are the rightful owner of spring-ai-openai-telegram-agent and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Model Context Protocol (MCP) Server is a Spring Boot application designed to provide domain-specific data, such as employee information, through a structured API.

Bot AI Agent – Spring Boot + Spring AI + OpenAI + Telegram Integration

Bot AI Agent is an intelligent assistant built with Spring Boot, Spring AI, and OpenAI, capable of interacting with users via:

  • a REST API (HTTP endpoints),
  • or a Telegram Bot.

The agent is designed to connect to an internal MCP Server that provides domain-specific data (e.g., employees, salaries, seniority, etc.).
Users can query the agent naturally — it understands the intent, fetches data from the MCP server, and formulates contextual answers.

Key Features

FeatureDescription
AI AssistantUses Spring AI + OpenAI for conversational understanding and reasoning
MCP Server IntegrationFetches employee data dynamically using internal API calls
REST APIExposes endpoints for external integrations and programmatic use
Telegram BotNatural chat interface to interact with the same backend agent
Modular DesignSeparate modules for bot-ai-agent and mcp-server
Configurable SecretsTokens and keys managed via environment variables or application.properties

Project Structure

  • mcp-server/ - Spring Boot application implementing the MCP Server
  • bot-ai-agent/ - Spring Boot application implementing the AI Agent with Telegram integration

code-structure.png

How It Works

  1. User Input

    • The user sends a message via Telegram or calls the REST API.

  2. AI Reasoning with MCPTools

    • The message is processed by Spring AI, powered by an OpenAI model.
    • The AI Agent analyzes the intent (e.g., “show me all employees” or “what’s Alice’s salary?”).

  3. Data Fetching (MCP Server)

    • The AI Agent calls the MCP Server to fetch structured data (like employee records).

  4. Response Generation

    • The agent formulates a human-readable, contextual response (e.g., explanations, summaries, stories).

  5. Delivery

    • The response is sent back via Telegram or returned as Stream.

Telegram Bot Demo

Example conversation:

teegram.png

Running the Project

Prerequisites

  • Java 21+
  • Spring Boot 3+
  • OpenAI API
  • Telegram Bots API
  • Maven

1 – Run MCP Server

cd mcp-server
mvn spring-boot:run

npx -y @modelcontextprotocol/inspector 
# Transport Type: Streamable HTTP
# URL: http://localhost:8989/mcp
# Connection Type: Via Proxy

modelcontextprotocol.png

MCP Server is a Spring Boot application that implements the Model Context Protocol (MCP) server functionality. it provide informations about employees

MCP Client (Main Application)

# in main directory
mvn spring-boot:run

It connect to MCP Server to fetch and display employee data using Model Context Protocol (MCP) Client. The MCP Client is built using Spring Boot and leverages the MCP Client dependency to communicate with the MCP Server.

Using OpenAI's GPT-4 API, the application can generate insights and summaries based on the fetched employee data or perform other AI-driven tasks. We car use browser to access the application and ask question like:

http://localhost:8087/ai-agent/chat?query=raconte%20moi%20une%20histoire%20sur%20l%27avenir%20de%20l%27ia%20generative%20et%20les%20entreprise

browser.png

Configuration

1. Environment Variables

Create a .env or configure your environment with:

OPENAI_API_KEY=sk-xxxxxxx
TELEGRAM_BOT_TOKEN=xxxxxxx

License

This project is licensed under the MIT License — feel free to use and adapt it.

Author