# Simple MCP Server
A simple, self-contained MCP (Model Context Protocol) server with basic utility functions. **No API keys, no credit cards, no external dependencies required!**
## Features
- **Get Current Time** - UTC and local time
- **Get Current Date** - Multiple date formats
- **Calculate** - Basic mathematical operations
- **Timezone Info** - Get timezone information
- **Generate Random Numbers** - Generate random numbers in a range
- **Execute Shell Commands** - Run shell commands and get output
- **Comprehensive Logging** - All requests logged to local file for monitoring
## Complete Setup Guide
### Step 1: Start the Server
1. **Navigate to the project directory:**
```bash
cd mcp
```
2. **Build and start the Docker container:**
```bash
docker compose up --build
```
This will:
- Build the Docker image
- Start the container
- Expose the server on port 8000
3. **Verify the server is running:**
```bash
# Check container status
docker compose ps
# Check logs (in another terminal)
docker compose logs -f mcp-server
# Test health endpoint (replace <remote-server-ip> with your server IP)
curl -H "X-API-Key: your-secure-api-key-here" http://<remote-server-ip>:8000/health
```
You should see:
- Container status: `Up`
- Logs showing: `Uvicorn running on http://0.0.0.0:8000`
- Health check returning: `{"status": "healthy"}`
### Step 2: Configure Cursor IDE
1. **Open Cursor IDE**
2. **Open Command Palette:**
- Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
- Type: `MCP Settings` or `MCP: Configure`
3. **Add New MCP Server:**
- Click "Add New" or "+" button
- You'll be prompted to add server configuration
4. **Enter Server Configuration:**
**Option A: Manual Entry**
- **Name**: `simple-utils-server`
- **URL**: `http://<remote-server-ip>:8000/sse`
- Replace `<remote-server-ip>` with your actual server IP address
- Example: `http://192.168.1.100:8000/sse` or `http://example.com:8000/sse`
- **Transport**: `sse` or `SSE`
- **Headers**: Add `X-API-Key: your-secure-api-key-here`
**Option B: Import from mcp.json**
- Open the `mcp.json` file in this repository
- Copy the entire contents
- Paste it into the MCP settings configuration
- **Important**: Replace `<remote-server-ip>` with your actual server IP address
- The configuration should look like:
```json
{
"mcpServers": {
"simple-utils-server": {
"url": "http://<remote-server-ip>:8000/sse",
"transport": "sse",
"headers": {
"X-API-Key": "your-secure-api-key-here"
}
}
}
}
```
5. **Save the Configuration:**
- Click "Save" or press `Enter`
- Cursor will automatically connect to the server
6. **Verify Connection:**
- Look for the MCP server status in Cursor's status bar
- It should show: `simple-utils-server: Connected`
- You should see 6 tools loaded
### Step 3: Test the Connection
1. **In Cursor's chat, try asking:**
```
"What time is it right now?"
```
2. **The AI should:**
- Automatically use the `get_current_time` tool
- Return the current time information
3. **Try other commands:**
```
"Calculate sqrt(144) + 5"
"Run the command 'echo hello world'"
"Get today's date"
```
### Troubleshooting Connection Issues
- **Server not connecting?**
- Verify server is running: `docker compose ps`
- Check server logs: `docker compose logs mcp-server`
- Test server directly: `curl http://<remote-server-ip>:8000/health`
- **Connection refused?**
- Check firewall allows port 8000
- Verify the IP address is correct
- Ensure server is listening on `0.0.0.0` (it is by default)
- **Tools not loading?**
- Restart Cursor completely
- Check MCP settings configuration is correct
- Verify the URL includes `/sse` at the end
## Security
The MCP server requires API key authentication for all requests.
### API Key Authentication
Set the `MCP_API_KEY` environment variable:
```bash
export MCP_API_KEY="your-secure-api-key-here"
```
All requests must include the API key in the `X-API-Key` header:
```bash
curl -H "X-API-Key: your-secure-api-key-here" http://your-server:8000/health
```
## Quick Start (Summary)
```bash
# 1. Start server
docker compose up --build
# 2. In Cursor: Ctrl+Shift+P -> MCP Settings -> Add New
# URL: http://<remote-server-ip>:8000/sse
# Transport: sse
# 3. Test: Ask "What time is it?"
```
## Available Tools
### 1. get_current_time
Get the current time in UTC and local timezone.
**Example:**
```json
{
"tool": "get_current_time",
"arguments": {}
}
```
### 2. get_current_date
Get the current date in various formats.
**Example:**
```json
{
"tool": "get_current_date",
"arguments": {
"format": "iso"
}
}
```
**Formats**: `iso`, `us`, `european`, `unix`
### 3. calculate
Perform basic mathematical calculations.
**Example:**
```json
{
"tool": "calculate",
"arguments": {
"expression": "sqrt(16) + 2 * 3"
}
}
```
**Supported functions**: `sqrt`, `sin`, `cos`, `tan`, `log`, `log10`, `exp`, `pow`, `abs`, `round`, `floor`, `ceil`, `min`, `max`, `sum`
**Constants**: `pi`, `e`
### 4. get_timezone_info
Get information about a timezone.
**Example:**
```json
{
"tool": "get_timezone_info",
"arguments": {
"timezone": "America/New_York"
}
}
```
### 5. generate_random_number
Generate random numbers within a specified range.
**Example:**
```json
{
"tool": "generate_random_number",
"arguments": {
"min_value": 1,
"max_value": 100,
"count": 5
}
}
```
**Parameters:**
- `min_value` (optional): Minimum value (default: 1)
- `max_value` (optional): Maximum value (default: 100)
- `count` (optional): Number of random numbers to generate (default: 1, max: 100)
**Returns:** Random number(s) with range information
### 6. execute_command
Execute a shell command and return the output. **WARNING: Use with caution as this can execute arbitrary commands.**
**Example:**
```json
{
"tool": "execute_command",
"arguments": {
"command": "ls -la",
"working_directory": "/tmp",
"timeout": 30
}
}
```
**Parameters:**
- `command` (required): Shell command to execute
- `working_directory` (optional): Working directory for the command
- `timeout` (optional): Timeout in seconds (default: 30)
**Example commands:**
- `"ls -la"` - List files
- `"echo hello world"` - Print text
- `"python --version"` - Check Python version
- `"pwd"` - Print working directory
- `"date"` - Get current date
## Testing
### Test with curl:
```bash
# Health check (replace <remote-server-ip> with your server IP)
curl http://<remote-server-ip>:8000/health
# Root endpoint
curl http://<remote-server-ip>:8000/
```
### Test MCP Tools (using HTTP directly):
The server uses SSE for MCP protocol, but you can test the basic endpoints.
## Firewall Configuration
If accessing from outside your VPS, open port 8000:
```bash
# Ubuntu/Debian
sudo ufw allow 8000/tcp
# CentOS/RHEL
sudo firewall-cmd --add-port=8000/tcp --permanent
sudo firewall-cmd --reload
```
## Development
### Run Locally (without Docker):
```bash
# Install dependencies
pip install -r requirements.txt
# Run the server
python server.py
```
The server will be available at `http://<remote-server-ip>:8000`
### Project Structure
```
mcp/
├── server.py # HTTP/SSE MCP server (for remote use)
├── requirements.txt # Python dependencies
├── Dockerfile # Docker image definition
├── docker-compose.yml # Docker compose configuration
└── README.md # This file
```
## Troubleshooting
1. **Container won't start**: Check logs with `docker compose logs mcp-server`
2. **Port already in use**: Change port in `docker-compose.yml`:
```yaml
ports:
- "8001:8000" # Use 8001 instead
```
3. **Can't connect from Cursor**:
- Verify firewall allows port 8000
- Check that container is running: `docker compose ps`
- Verify the URL is correct: `http://<remote-server-ip>:8000/sse`
4. **Connection refused**:
- Ensure the server is listening on `0.0.0.0` (it is by default)
- Check VPS firewall rules
## Security Notes
- The server has CORS enabled for all origins (for testing)
- For production, consider:
- Restricting CORS origins
- Adding authentication
- Using HTTPS with a reverse proxy (nginx/traefik)
- Restricting firewall access to trusted IPs
## Useful Commands
```bash
# View logs
docker compose logs -f mcp-server
# Restart the server
docker compose restart mcp-server
# Stop the server
docker compose down
# Rebuild and restart
docker compose up -d --build
# Check container status
docker compose ps
```
## No External Dependencies!
This server uses only:
- Python standard library (datetime, math, json)
- MCP SDK (for protocol)
- FastAPI/Uvicorn (for HTTP server)
## Logging
The server automatically logs all requests to a local text file (`requests_log.txt`) with comprehensive information including:
- **Client Information**: IP address, User-Agent, headers, etc.
- **Request Details**: Tool called, arguments, timestamps
- **Response Data**: Full response content, success/failure status
- **Server Info**: Request ID, server version, processing time
### Log File Format
Each log entry includes:
- Unique request ID
- UTC timestamp
- Complete request/response data in JSON format
- Success/failure indicators
### Viewing Logs
```bash
# View recent logs (on host machine)
tail -f logs/requests_log.txt
# Search for specific tool calls
grep "tool_name" logs/requests_log.txt
# Count total requests
grep "REQUEST LOG ENTRY" logs/requests_log.txt | wc -l
```
**Note:** The log file is automatically persisted on the host machine in the `./logs/` directory using Docker volumes. This means logs survive container restarts and can be accessed even after the container is stopped. The logs contain sensitive information - monitor them for security and debugging purposes.
## No External Dependencies!
This server uses only:
- Python standard library (datetime, math, json, random, os, sys, uuid)
- MCP SDK (for protocol)
- FastAPI/Uvicorn (for HTTP server)
**No API keys, no credit cards, no external services required!**
