docdyhr/simplenote-mcp-server repository overview

⁠Simplenote MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Simplenote⁠ for note management, search, and organization capabilities. Built with enterprise-grade security and performance optimization.

⁠🚀 Quick Start

⁠Using Docker Compose (Recommended)

services:
  simplenote-mcp:
    image: docdyhr/simplenote-mcp-server:latest
    container_name: simplenote-mcp-server
    restart: unless-stopped
    environment:
      - [email protected]
      - SIMPLENOTE_PASSWORD=your-password
    ports:
      - "8000:8000"
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=100m

⁠Using Docker Run

docker run -d \
  --name simplenote-mcp-server \
  --restart unless-stopped \
  -e [email protected] \
  -e SIMPLENOTE_PASSWORD=your-password \
  -p 8000:8000 \
  --security-opt no-new-privileges:true \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  docdyhr/simplenote-mcp-server:latest

⁠🔧 Configuration

⁠Required Environment Variables

⁠Optional Environment Variables

⁠🏗️ Container Features

⁠🛡️ Security Hardened

• ✅ Non-root user - Runs as dedicated mcp user
• ✅ Read-only filesystem - Immutable container runtime
• ✅ No privilege escalation - Security-first design
• ✅ Minimal attack surface - Distroless-style base image
• ✅ Signed images - Cosign keyless signing
• ✅ Vulnerability scanned - Trivy + Docker Scout

⁠⚡ Performance Optimized

• 📦 97MB image size - Multi-stage build optimization
• 🚀 Fast startup - Intelligent caching and lazy loading
• 💾 Memory efficient - <256MB runtime memory usage
• 🔄 Health checks - Built-in container health monitoring

⁠🏢 Production Ready

• 🌐 Multi-architecture - AMD64 and ARM64 support
• 📊 Observability - Comprehensive logging and metrics
• 🔄 Graceful shutdown - Proper signal handling
• 📈 Resource limits - CPU and memory constraints
• 🔒 SLSA attestation - Supply chain security

⁠🌟 Capabilities

⁠Note Management

• 📝 Create notes - Rich text content with tags
• ✏️ Update notes - Modify content and metadata
• 🗑️ Delete notes - Safe note removal
• 📋 List notes - Paginated note browsing
• 🔍 Search notes - Advanced search with filters

⁠Tag Management

• 🏷️ Add tags - Organize notes with tags
• 🗂️ Remove tags - Clean up tag assignments
• 🔄 Replace tags - Bulk tag operations
• 📊 Tag statistics - Usage analytics

⁠Advanced Search

• 🔎 Full-text search - Content and title searching
• 📅 Date filtering - Time-based note retrieval
• 🏷️ Tag filtering - Category-based search
• 🔤 Boolean operators - AND, OR, NOT queries
• 📝 Phrase matching - Exact phrase searches

⁠🏥 Health Checks

The container includes built-in health monitoring:

# Check container health
docker exec simplenote-mcp-server python -c "import simplenote_mcp; print('✅ Healthy')"

# View health status
docker inspect --format='{{.State.Health.Status}}' simplenote-mcp-server

⁠📊 Usage Examples

⁠Basic MCP Client Integration

import asyncio
from mcp import StdioServerManager


async def main():
    async with StdioServerManager(
        "docker",
        [
            "run",
            "--rm",
            "-i",
            "-e",
            "[email protected]",
            "-e",
            "SIMPLENOTE_PASSWORD=your-password",
            "docdyhr/simplenote-mcp-server:latest",
        ],
    ) as server:
        # List available tools
        tools = await server.list_tools()
        print(f"Available tools: {[tool.name for tool in tools.tools]}")

        # Search notes
        result = await server.call_tool("search_notes", {"query": "important"})
        print(f"Search results: {result}")

⁠Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "simplenote": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/simplenote.env",
        "docdyhr/simplenote-mcp-server:latest"
      ]
    }
  }
}

⁠🔄 Updates & Versions

⁠Available Tags

⁠Automatic Updates

Images are automatically rebuilt weekly with security updates every Sunday at 2 AM UTC.

# Update to latest version
docker pull docdyhr/simplenote-mcp-server:latest
docker-compose up -d  # Recreate containers

⁠🔐 Security

⁠Vulnerability Scanning

• Trivy: Container and filesystem scanning
• Docker Scout: Advanced vulnerability analysis
• Automated scans: Every build and weekly rebuilds

⁠Image Signing

All images are signed with Cosign for supply chain security:

# Verify image signature
cosign verify docdyhr/simplenote-mcp-server:latest

⁠SLSA Attestation

Build provenance attestations available for compliance:

# View build attestation
cosign verify-attestation docdyhr/simplenote-mcp-server:latest

⁠🆘 Troubleshooting

⁠Common Issues

⁠Authentication Errors

# Check credentials
docker logs simplenote-mcp-server | grep -i auth

# Verify environment variables
docker exec simplenote-mcp-server env | grep SIMPLENOTE

⁠Connection Issues

# Test network connectivity
docker exec simplenote-mcp-server curl -I https://app.simplenote.com

# Check container health
docker exec simplenote-mcp-server python -c "import simplenote_mcp; print('OK')"

⁠Performance Issues

# Monitor resource usage
docker stats simplenote-mcp-server

# Check memory limits
docker inspect simplenote-mcp-server | jq '.[0].HostConfig.Memory'

⁠Debug Mode

Enable detailed logging for troubleshooting:

docker run --rm -it \
  -e [email protected] \
  -e SIMPLENOTE_PASSWORD=your-password \
  -e LOG_LEVEL=DEBUG \
  docdyhr/simplenote-mcp-server:latest

⁠📚 Documentation

• Full Documentation: GitHub Repository⁠
• API Reference: Tools and Resources Guide⁠
• Configuration Guide: Setup Instructions⁠
• Development Guide: Contributing⁠

⁠📄 License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠🤝 Support

• Issues: GitHub Issues⁠
• Discussions: GitHub Discussions⁠
• Security: Security Policy⁠

Maintained by: Thomas Juul Dyhr⁠
Source Code: GitHub Repository⁠
Container Registry: Docker Hub⁠