simplenote-mcp-server
3.3
If you are the rightful owner of simplenote-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Simplenote MCP Server is a lightweight server that integrates Simplenote with Claude Desktop using the MCP Python SDK.
Simplenote MCP Server
A lightweight MCP server that integrates Simplenote with Claude Desktop using the MCP Python SDK.
This allows Claude Desktop to interact with your Simplenote notes as a memory backend or content source.
🔧 Features
- 📝 Full Note Management: Read, create, update, and delete Simplenote notes
- 🔍 Advanced Search: Boolean operators, phrase matching, tag and date filters
- ⚡ High Performance: In-memory caching with background synchronization
- 🔐 Secure Authentication: Token-based authentication via environment variables
- 🧩 MCP Compatible: Works with Claude Desktop and other MCP clients
- 🐳 Docker Ready: Full containerization with multi-stage builds and security hardening
- 📊 Monitoring: Optional performance metrics and monitoring
🚀 Quick Start
Option 1: Docker (Recommended)
The fastest way to get started is using our pre-built Docker image:
# Pull and run the latest image
docker run -d \
-e SIMPLENOTE_EMAIL=your.email@example.com \
-e SIMPLENOTE_PASSWORD=your-password \
-p 8000:8000 \
docdyhr/simplenote-mcp-server:latest
Or use Docker Compose:
# Clone the repository for docker-compose.yml
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
# Set environment variables
export SIMPLENOTE_EMAIL=your.email@example.com
export SIMPLENOTE_PASSWORD=your-password
# Run with Docker Compose
docker-compose up -d
Option 2: Smithery (One-click install)
Install automatically via Smithery:
npx -y @smithery/cli install @docdyhr/simplenote-mcp-server --client claude
This method automatically configures Claude Desktop with the MCP server.
Option 3: Traditional Python Install
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e .
simplenote-mcp-server
🐳 Docker Deployment
Using Pre-built Images
The easiest way to use the server is with our pre-built Docker images:
# Pull the latest image
docker pull docdyhr/simplenote-mcp-server:latest
# Run with Docker
docker run -d \
-e SIMPLENOTE_EMAIL=your.email@example.com \
-e SIMPLENOTE_PASSWORD=your-password \
-p 8000:8000 \
docdyhr/simplenote-mcp-server:latest
# Or use Docker Compose
docker-compose up -d
Available tags:
latest- Latest stable releasev1.6.0- Specific versionmain- Latest development build
Production Deployment
# Build and run the production container
docker-compose up -d
# Or build manually
docker build -t simplenote-mcp-server .
docker run -d \
-e SIMPLENOTE_EMAIL=your.email@example.com \
-e SIMPLENOTE_PASSWORD=your-password \
-p 8000:8000 \
simplenote-mcp-server
Development with Docker
# Use the development compose file for live code mounting
docker-compose -f docker-compose.dev.yml up
Docker Features
- Multi-stage build for optimized image size (346MB)
- Multi-platform support:
linux/amd64andlinux/arm64 - Security hardening: Non-root user, read-only filesystem, no new privileges
- Health checks and automatic restart policies
- Resource limits: 1 CPU, 512MB memory
- Logging: Persistent log volumes
- Environment-based configuration
- CI/CD Pipeline: Automated builds and publishing to Docker Hub
- Security scanning: Trivy vulnerability scanning on all images
- Container signing: Sigstore cosign signatures for supply chain security
- Kubernetes ready: Production-grade Helm chart with security hardening
- Automated updates: Dependabot for dependencies, auto-versioning workflows
- Health monitoring: Continuous health checks and alerting
- Enterprise notifications: Slack and email integration for CI/CD status
☸️ Kubernetes Deployment
Using Helm (Recommended)
Deploy to Kubernetes with our production-ready Helm chart:
# Install from local chart
helm install my-simplenote ./helm/simplenote-mcp-server \
--set simplenote.email="your-email@example.com" \
--set simplenote.password="your-password"
# Or with external secrets (recommended for production)
helm install my-simplenote ./helm/simplenote-mcp-server \
--set externalSecrets.enabled=true \
--set externalSecrets.secretStore.name="vault-backend"
Kubernetes Features
- Security hardening: Non-root user, read-only filesystem, dropped capabilities
- Resource management: CPU/memory limits and requests configured
- Auto-scaling: Horizontal Pod Autoscaler support
- Health checks: Liveness and readiness probes
- External secrets: Integration with external secret management
- Service mesh ready: Compatible with Istio and other service meshes
Production Configuration
# values.yaml for production
replicaCount: 3
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10
resources:
limits:
cpu: 1000m
memory: 512Mi
requests:
cpu: 500m
memory: 256Mi
⚙️ Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
SIMPLENOTE_EMAIL | Yes | - | Your Simplenote account email |
SIMPLENOTE_PASSWORD | Yes | - | Your Simplenote account password |
SYNC_INTERVAL_SECONDS | No | 120 | Cache synchronization interval |
LOG_LEVEL | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
Claude Desktop Integration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"simplenote": {
"description": "Access and manage your Simplenote notes",
"command": "simplenote-mcp-server",
"env": {
"SIMPLENOTE_EMAIL": "your.email@example.com",
"SIMPLENOTE_PASSWORD": "your-password"
}
}
}
}
🔍 Advanced Search
Powerful search with boolean logic and filters:
# Boolean operators
project AND meeting AND NOT cancelled
# Phrase matching
"action items" AND project
# Tag filtering
meeting tag:work tag:important
# Date ranges
project from:2023-01-01 to:2023-12-31
# Combined query
"status update" AND project tag:work from:2023-01-01 NOT cancelled
🛠️ Available Tools
| Tool | Description | Parameters |
|---|---|---|
create_note | Create a new note | content, tags (optional) |
update_note | Update an existing note | note_id, content, tags (optional) |
delete_note | Move a note to trash | note_id |
get_note | Get a note by ID | note_id |
search_notes | Advanced search with filters | query, limit, offset, tags, from_date, to_date |
add_tags | Add tags to a note | note_id, tags |
remove_tags | Remove tags from a note | note_id, tags |
replace_tags | Replace all tags on a note | note_id, tags |
📊 Performance & Caching
- In-memory caching with background synchronization
- Pagination support for large note collections
- Indexed lookups for tags and content
- Query result caching for repeated searches
- Optimized API usage with minimal Simplenote calls
🛡️ Security
- Token-based authentication via environment variables
- No hardcoded credentials in Docker images
- Security-hardened containers with non-root users
- Read-only filesystem in production containers
- Resource limits to prevent abuse
🚨 Troubleshooting
Common Issues
Authentication Problems:
- Verify
SIMPLENOTE_EMAILandSIMPLENOTE_PASSWORDare set correctly - Check for typos in credentials
Docker Issues:
# Check container logs
docker-compose logs
# Restart services
docker-compose restart
# Rebuild if needed
docker-compose up --build
Claude Desktop Connection:
# Verify tools are available
./simplenote_mcp/scripts/verify_tools.sh
# Monitor logs
./simplenote_mcp/scripts/watch_logs.sh
Diagnostic Commands
# Test connectivity
python simplenote_mcp/tests/test_mcp_client.py
# Check server status
./simplenote_mcp/scripts/check_server_pid.sh
# Clean up and restart
./simplenote_mcp/scripts/cleanup_servers.sh
📚 Development
Local Development
# Clone and setup
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e ".[dev,test]"
# Run tests
pytest
# Code quality
ruff check .
ruff format .
mypy simplenote_mcp
Docker Development
# Development with live code reload
docker-compose -f docker-compose.dev.yml up
# Build and test
docker build -t simplenote-mcp-server:test .
docker run --rm simplenote-mcp-server:test --help
🤝 Contributing
Contributions are welcome! Please read for guidelines.
📄 License
This project is licensed under the MIT License - see the file for details.
🔗 Related Projects
