A
licenseNot graded
qualityD
maintenanceMCP server for Twilio communications, enabling SMS/MMS sending, message listing, outbound calls, and phone number lookup.
MIT
FastMCP SMS Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FastMCP SMS ServerSend a text message to 555-1234 saying 'Meeting at 3pm'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π± FastMCP SMS Server
A production-oriented Model Context Protocol (MCP) server built with FastMCP, JWT authentication, SQLAlchemy, and the TextBee SMS API.
This project demonstrates how an MCP server can authenticate users, identify the authenticated user from a JWT, access user-specific data through SQLAlchemy, and expose SMS functionality as an MCP tool.
β¨ Features
π FastMCP server
π JWT authentication with RS256
π Public/private RSA key verification
π€ User registration and login
ποΈ SQLAlchemy database integration
π« Access token based authentication
π§βπ» Authenticated user identification using JWT
subπ± Send SMS through TextBee
π User-specific API credentials
π€ MCP client support
π₯οΈ Claude Desktop integration
β‘ FastAPI authentication server
Related MCP server: Sms Verify3 MCP Server
ποΈ Architecture
βββββββββββββββββββββββ
β Claude Desktop β
β MCP Client β
ββββββββββββ¬βββββββββββ
β
β MCP
βΌ
βββββββββββββββββββββββ
β FastMCP Server β
β β
β JWT Verification β
β MCP Tools β
ββββββββββββ¬βββββββββββ
β
ββββββββββββ΄βββββββββββ
β β
βΌ βΌ
βββββββββββββββ ββββββββββββββββ
β SQLAlchemy β β TextBee β
β Database β β SMS API β
βββββββββββββββ ββββββββββββββββ
β²
β
β user_id
β
βββββββββββββββ
β JWT Token β
β β
β sub β
β username β
β scope β
β iss β
β aud β
βββββββββββββββπ Project Structure
mcp/
β
βββ src/
β β
β βββ auth_server/
β β βββ __init__.py
β β βββ main.py
β β βββ database.py
β β βββ models.py
β β βββ schemas.py
β β βββ security.py
β β
β βββ mcp_server.py
β βββ mcp_database.py
β βββ client.py
β
βββ keys/
β βββ private_key.pem
β βββ public_key.pem
β
βββ .gitignore
βββ requirements.txt
βββ README.mdNever commit
private_key.pemor real API credentials to GitHub.
π οΈ Technologies
Technology | Purpose |
Python | Backend |
FastMCP | MCP server |
FastAPI | Authentication server |
SQLAlchemy | Database ORM |
SQLite | Development database |
PyJWT | JWT creation and verification |
Cryptography | RSA cryptography |
Pwdlib | Password hashing |
HTTPX | HTTP requests |
TextBee | SMS delivery |
π Installation
1. Clone the repository
git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY2. Create a virtual environment
Windows
python -m venv .venvActivate it:
.venv\Scripts\activateLinux / macOS
python3 -m venv .venv
source .venv/bin/activate3. Install dependencies
pip install -r requirements.txtπ Generate RSA Keys
This project uses RS256.
The authentication server signs JWTs using the private key:
private_key.pemThe MCP server verifies them using:
public_key.pemGenerate a key pair with OpenSSL:
openssl genrsa -out keys/private_key.pem 2048Then:
openssl rsa \
-in keys/private_key.pem \
-pubout \
-out keys/public_key.pemOn Windows PowerShell, the same commands can be run if OpenSSL is installed.
π€ Authentication Server
The authentication server provides:
POST /register
POST /loginStart it with:
uvicorn auth_server.main:app --port 9000The authentication server will run at:
http://127.0.0.1:9000π Register a User
Example:
curl.exe -X POST http://127.0.0.1:9000/register `
-H "Content-Type: application/json" `
-d '{\"username\":\"kanchan\",\"password\":\"1234\"}'Response:
{
"message": "User created successfully",
"user_id": 1,
"username": "kanchan"
}π Login
curl.exe -X POST http://127.0.0.1:9000/login `
-H "Content-Type: application/json" `
-d '{\"username\":\"kanchan\",\"password\":\"1234\"}'Response:
{
"access_token": "YOUR_JWT_TOKEN",
"token_type": "bearer"
}The JWT contains claims such as:
{
"sub": "1",
"username": "kanchan",
"scope": "profile:read",
"iss": "http://localhost:9000",
"aud": "my-mcp-server",
"iat": 1234567890,
"exp": 1234571490
}π JWT Authentication
The MCP server uses an RSA public key to verify the JWT.
verifier = JWTVerifier(
public_key=PUBLIC_KEY,
issuer="http://localhost:9000",
audience="my-mcp-server",
algorithm="RS256",
)The authentication flow is:
User
β
β username + password
βΌ
Auth Server
β
β signs JWT with private key
βΌ
Access Token
β
βΌ
MCP Client
β
β Bearer token
βΌ
FastMCP
β
β verifies signature with public key
βΌ
MCP ToolποΈ SQLAlchemy Integration
The MCP tools use SQLAlchemy to access the database.
A database session is created using:
db = SessionLocal()Example:
stmt = select(User).where(User.id == user_id)
user = db.scalar(stmt)The session is closed after the operation:
finally:
db.close()π€ Getting the Authenticated User
The MCP server does not need the client to provide a user_id.
Instead, the user ID comes from the verified JWT:
token = get_access_token()
user_id = int(token.claims["sub"])Then SQLAlchemy can find the user:
stmt = select(User).where(User.id == user_id)
user = db.scalar(stmt)This gives the MCP server the identity of the user who made the request.
π± Send SMS Tool
The project exposes an MCP tool similar to:
@mcp.tool()
def send_sms(
recipient: str,
message: str,
) -> dict:
...The client only needs to provide:
recipient
messageIt does not need to provide:
user_id
api_key
device_idThe server can determine the authenticated user from the JWT and retrieve that user's TextBee configuration from the database.
π€ Claude Desktop
The MCP server can be connected to Claude Desktop as a local MCP server.
Example configuration:
{
"mcpServers": {
"my-mcp-server": {
"command": "E:\\mcp\\.venv\\Scripts\\python.exe",
"args": [
"E:\\mcp\\src\\mcp_server.py"
]
}
}
}The configuration file is located at:
%APPDATA%\Claude\claude_desktop_config.jsonAfter modifying the configuration, restart Claude Desktop.
Your MCP tools should then become available to Claude.
β οΈ Security
Do not commit secrets to GitHub.
Add the following to .gitignore:
.venv/
__pycache__/
*.pyc
.env
.env.*
users.db
keys/private_key.pem
*.logNever commit:
private_key.pemor:
TextBee API keys
JWT secrets
database passwordsFor production, store secrets in environment variables or a dedicated secrets manager.
π Current Authentication Flow
ββββββββββββββββ
β User β
ββββββββ¬ββββββββ
β
β Login
βΌ
ββββββββββββββββββββ
β Auth Server β
β FastAPI β
ββββββββββ¬ββββββββββ
β
β RS256 JWT
βΌ
ββββββββββββββββββββ
β MCP Client β
β Claude / Custom β
ββββββββββ¬ββββββββββ
β
β Access Token
βΌ
ββββββββββββββββββββ
β FastMCP Server β
β β
β JWTVerifier β
ββββββββββ¬ββββββββββ
β
β Verified JWT
βΌ
ββββββββββββββββββββ
β MCP Tool β
β β
β get_access_token β
ββββββββββ¬ββββββββββ
β
β sub β user_id
βΌ
ββββββββββββββββββββ
β SQLAlchemy β
β β
β User β
ββββββββββ¬ββββββββββ
β
β User credentials
βΌ
ββββββββββββββββββββ
β TextBee β
β SMS Gateway β
ββββββββββββββββββββπ§ͺ Development
Start the authentication server:
uvicorn auth_server.main:app --port 9000Start the MCP server:
python mcp_server.pyFor Claude Desktop, configure the MCP server using the stdio transport.
π§ Roadmap
FastMCP server
FastAPI authentication server
User registration
User login
JWT authentication
RS256 signing
SQLAlchemy integration
Authenticated user lookup
TextBee SMS integration
Claude Desktop local integration
OAuth 2.0 authorization server
Multi-user TextBee credential management
PostgreSQL support
Refresh tokens
Token revocation
Production deployment
HTTPS
Rate limiting
Audit logging
π What This Project Demonstrates
This project is primarily a learning and development example for understanding how the following technologies work together:
MCP
+
FastMCP
+
JWT
+
RS256
+
FastAPI
+
SQLAlchemy
+
External APIsThe main goal is to demonstrate how an MCP tool can securely identify the authenticated user and perform user-specific operations.
π License
This project is available under the MIT License.
See LICENSE for details.
β Contributing
Contributions, suggestions, and improvements are welcome.
If you find a bug or have an idea, feel free to open an issue or submit a pull request.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
The Mobile Text Alerts SMS MCP server enables your AI to send SMS messages & manage contacts
Official EZTexting MCP server: SMS/MMS messaging, contacts, workflows, reports.
An authenticated remote MCP server for user-owned devices and one-shot capability invocation.
Hosted MCP server for the Wavix telecom platform: SMS, voice, 2FA, SIP, numbers, 10DLC, CDRs.
Related MCP Servers
- FlicenseCqualityDmaintenanceMCP server for accessing Sms Verify3 API to send numeric verification codes and estimate costs.1-
- FlicenseAqualityDmaintenanceMCP server for sending SMS messages via SmsManager.cz HTTP API, supporting high, economy, and low delivery gateways.1-
- AlicenseNot gradedqualityAmaintenanceMCP server that provides SMS sending, CSV bulk SMS, and voice calling capabilities via the Vonage API.Apache 2.0