Simplenote Mcp Server

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.

[](https://github.com/docdyhr/simplenote-mcp-server/actions/workflows/unified-ci.yml) [](https://github.com/docdyhr/simplenote-mcp-server/actions/workflows/security.yml)

[](https://github.com/docdyhr/simplenote-mcp-server) [](./CHANGELOG.md) [](./htmlcov/index.html) [](https://opensource.org/licenses/MIT)

[](https://pypi.org/project/simplenote-mcp-server/) [](https://hub.docker.com/r/docdyhr/simplenote-mcp-server) [](https://github.com/docdyhr/simplenote-mcp-server)

[](https://github.com/modelcontextprotocol) [](https://github.com/psf/black) [](https://github.com/astral-sh/ruff) [](https://smithery.ai/server/@docdyhr/simplenote-mcp-server)

[](https://mseep.ai/app/b215d030-b511-457d-8a6d-3e1e6ea3b541) ---

What's New (Unreleased)

26 Tools — Full Bear Parity + Simplenote Differentiators + Claude Companion Tools

Two new irreversible-deletion tools with mandatory safety guards:

• permanent_delete_note: Permanently destroy a single note; requires confirm=true; dry-run preview by default
• empty_trash: Permanently delete all trashed notes; defaults to dry_run=true (preview); requires dry_run=false AND confirm=true
• 1188 tests passing, 77% coverage, zero linting/type errors

v1.17.0

• search_notes async fix: Boolean AND queries no longer hang the server; search now runs in a thread-pool executor with a 30 s timeout
• Substring pre-filter: searching "test" now correctly returns notes containing "testing", "tested", etc.
• Real-engine integration test suite added; import error in test helpers fixed

v1.16.0

• publish_note: Publish a note to a public URL — unique to Simplenote MCP; returns public_url
• unpublish_note: Remove a note from public access; no-op if already unpublished

See the [CHANGELOG](./CHANGELOG.md) for complete details.

See the [CHANGELOG](./CHANGELOG.md) for complete details.

---

🔧 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 HTTP endpoints for health, readiness, and metrics
• 🧪 Robust Testing: Comprehensive test suite with 1135+ tests and continuous integration
• 🔒 Security Hardened: Regular security scanning with Bandit, pip-audit, and dependency checks

---

🚀 Quick Start

Prerequisites

• Simplenote account (create one at simplenote.com)
• Python 3.10+ (for non-Docker installs) or Docker

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 \
  --name simplenote-mcp \
  -e SIMPLENOTE_EMAIL=your.email@example.com \
  -e SIMPLENOTE_PASSWORD=your-password \
  -p 8000:8000 \
  docdyhr/simplenote-mcp-server:latest

Docker Health Checks: The container includes built-in health monitoring endpoints:

• Health: http://localhost:8000/health
• Readiness: http://localhost:8000/ready
• Metrics: http://localhost:8000/metrics (Prometheus format)

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

---

🗂 Documentation Map & Archives

• Start with docs/DOCUMENTATION_GUIDE.md for a curated tour of user, developer, and operations docs plus maintenance checklists.
• Historical project summaries now live under docs/archive/2025/, keeping the repository root focused on active roadmaps and guides.
• Need something fast? Run rg "" docs/ or jump to docs/index.md for the MkDocs-style table of contents.

---

🐳 Docker Deployment

Container Features

• Multi-stage builds for optimized image size
• Security hardening with non-root user and minimal attack surface
• Health monitoring endpoints built-in
• Resource limits and proper signal handling
• Volume support for persistent data

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 release
• v1.17.0 - Specific version
• main - 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/amd64 and linux/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 in seconds | | CACHE_MAX_SIZE | No | 10000 | Max notes held in memory — set ≥ your total note count | | LOG_LEVEL | No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) | | SIMPLENOTE_OFFLINE_MODE | No | false | Skip API calls; used for testing without credentials |

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",
        "CACHE_MAX_SIZE": "10000"
      }
    }
  }
}

---

🔍 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 | Replace full note content (destructive) | note_id, content, tags (optional) | | delete_note | Soft-delete: move note to Trash | note_id | | restore_note | Untrash a note — move it back from Trash | note_id | | permanent_delete_note | Irreversibly destroy a single note (requires confirm=true) | note_id, confirm | | empty_trash | Permanently delete all trashed notes (dry-run by default) | dry_run (default true), confirm (default false) | | get_note | Get a note by ID with full content and metadata | note_id | | add_text | Append or prepend text without overwriting | note_id, text, position ("end" \| "beginning") | | search_notes | Full-text search with filters and pagination | query, limit, offset, tags, from_date, to_date, created_after, modified_after, pinned, fuzzy, sort_by | | add_tags | Add tags to a note | note_id, tags | | remove_tags | Remove specific tags from a note | note_id, tags | | replace_tags | Replace all tags on a note | note_id, tags | | list_tags | List all tags with note counts | sort_by ("alpha" \| "count") | | rename_tag | Rename a tag across all notes atomically | old_tag, new_tag, dry_run (optional) | | get_note_versions | List version history for a note | note_id | | restore_version | Roll back a note to a previous version | note_id, version_number | | get_or_create_note | Atomic find-or-create by title | title, tags (optional), default_content (optional) | | append_to_daily_note | Append a timestamped entry to today's note | text, tags (optional) | | replace_section | Replace one Markdown section without touching others | note_id, header, content | | find_untagged_notes | Find notes with no tags | limit (optional) | | bulk_tag | Apply tags to multiple notes in one call | note_ids, tags | | export_notes | Export notes to Markdown or JSON | format, tags (optional), query (optional) | | find_and_merge_duplicates | Detect and merge duplicate notes | dry_run (optional), similarity_threshold (optional) | | get_server_info | Server version, author, and runtime debug info | (no parameters) |

---

📊 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

---

🎯 Recent Improvements

✅ January 2025 - Performance & Code Quality

Critical Bug Fix:

• Fixed Claude Desktop timeout - Reduced startup time from 55+ seconds to = 15) → 0 (100% reduction)
• Maintainability improved: Cache MI from 12.7 → 16.2 (+28%)
• Extracted 23 helper methods for better code organization
• All 670 tests passing with 67% cache coverage maintained
• See REFACTORING_PHASE1_COMPLETE.md for details

**Documentation Enhancemen

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: docdyhr
• Source: docdyhr/simplenote-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.