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.

🎉 What's New in v1.9.0

Major Performance Breakthrough - Production Ready!

Version 1.9.0 delivers a 98% startup performance improvement and marks the project as fully production-ready for Claude Desktop integration:

• 🚀 Startup Time: Reduced from 55+ seconds to < 1 second (98% improvement)

• ✅ Claude Desktop Ready: Fixed critical timeout issue preventing MCP integration

• 📊 Code Quality: 21% reduction in high-complexity functions, Phase 1 refactoring complete

• 📚 Complete Documentation: Comprehensive guides, templates, and production validation

• 🎯 Zero Technical Debt: 0 open issues, 0 open PRs, all quality gates passing

• 🏆 Grade A+ Health: 756 tests passing, 69.64% coverage, 100% CI success rate

Key Improvements:

• Thread pool execution for blocking Simplenote API calls

• True non-blocking cache initialization with background loading

• Graceful empty cache handling during startup

• Enhanced monitoring and complexity analysis tools

• GitHub issue templates for better community engagement

See the CHANGELOG 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 700+ 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:

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:

Option 2: Smithery (One-click install)

Install automatically via Smithery:

This method automatically configures Claude Desktop with the MCP server.

Option 3: Traditional Python Install

🗂 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 "<topic>" 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:

Available tags:

• latest - Latest stable release

• v1.10.0 - Specific version

• main - Latest development build

Production Deployment

Development with Docker

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:

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

⚙️ Configuration

Environment Variables

Claude Desktop Integration

Add to your claude_desktop_config.json:

🔍 Advanced Search

Powerful search with boolean logic and filters:

🛠️ Available Tools

📊 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 < 1 second (98% improvement)

• Implemented thread pool execution for blocking Simplenote API calls

• Made cache initialization truly non-blocking with background loading

• Resolved anyio.BrokenResourceError during shutdown

Code Refactoring - Phase 1 Complete:

• Cache module complexity reduced: 5 high-complexity functions (CC >= 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 Enhancements:

• Added comprehensive CHANGELOG.md with complete version history

• Created TESTING_CLAUDE_DESKTOP.md for user testing guide

• Added code complexity analysis tools (check_complexity.py)

• Documented refactoring plan and completion reports

Quality Tools:

• Integrated Radon for automated complexity analysis

• Baseline metrics: 22 functions CC >= 15 (down from 28)

• Average Maintainability Index: 57.9 (maintained)

• Zero diagnostics errors, all quality gates passing

✅ September 2025 - Quality & Reliability Enhancements

✅ Quality & Reliability Enhancements

Test Suite Stabilization:

• Fixed test isolation issues that caused intermittent failures

• Improved test cleanup with proper timeout handling

• Enhanced fixture management for better test reliability

• Achieved consistent test results across individual and suite runs

CI/CD Pipeline Optimization:

• Consolidated 28 workflows down to 16 active workflows

• Implemented unified monitoring workflow combining security, health, and badge checks

• Improved test coverage reporting with realistic 15.6% baseline

• Enhanced Docker build validation and security scanning

Code Quality Improvements:

• All linting (Ruff), formatting, and type checking (MyPy) now pass consistently

• Zero high-severity security vulnerabilities (verified with Bandit, pip-audit, safety)

• Standardized code formatting and pre-commit hooks configuration

• Enhanced error handling and user-facing error messages

🔧 Developer Experience

Improved Testing:

• 724 comprehensive tests covering core functionality

• Function-scoped fixtures for better test isolation

• Realistic coverage baseline established (15.6%)

• Streamlined test execution with proper cleanup

Enhanced Documentation:

• Updated deployment guides with current Docker setup

• Improved health monitoring endpoint documentation

• Added troubleshooting guides for common issues

• Current status and roadmap documentation

Container Improvements:

• Multi-stage Docker builds for optimized image size

• Built-in health monitoring endpoints (/health, /ready, /metrics)

• Enhanced security hardening with non-root user

• Improved signal handling and graceful shutdown

🧪 Testing & Evaluation

MCP Evaluations ✅

Status: ✅ WORKING - Complete mcp-evals integration with TypeScript wrapper!

This project includes comprehensive evaluations using mcp-evals to ensure reliability and performance:

Latest Test Results: 4/5 tests passing excellently (avg 4.1/5):

• Server Startup: 4.6/5 ⭐ (Excellent)

• Authentication: 4.0/5 ⭐ (Good)

• Note Operations: 3.8/5 ⭐ (Good)

• Search: 5.0/5 ⭐ (Perfect)

• Error Handling: 1.4/5 ⚠️ (Needs improvement)

Evaluation Types

• Smoke Tests: Basic functionality validation

• CRUD Operations: Note creation, reading, updating, deletion

• Search & Filtering: Boolean search, tag filtering, date ranges

• Error Handling: Authentication, network issues, edge cases

• Performance: Large datasets, concurrent operations

• Security: Input validation, authentication enforcement

Automated Testing

Evaluations run automatically on:

• Pull Requests: Smoke + basic tests

• Releases: Comprehensive evaluation suite

• Manual Trigger: Full test matrix with detailed reporting

The evaluations use OpenAI's GPT models to assess:

• Accuracy: Correctness of responses

• Completeness: Thoroughness of results

• Relevance: Response appropriateness

• Clarity: Response readability

• Performance: Operation efficiency

📁 See evals/README.md for detailed evaluation documentation.

Traditional Testing

🛡️ 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_EMAIL and SIMPLENOTE_PASSWORD are set correctly

• Check for typos in credentials

Docker Issues:

Claude Desktop Connection:

Diagnostic Commands

📚 Development

Quick Setup with mcp-evals

Local Development

Development Environment

The setup script creates:

• Python development environment with all dependencies

• Node.js environment for mcp-evals

• Example configuration files

• Pre-commit hooks

• Validation for all evaluation files

Testing Strategy

1. Unit Tests: Traditional Python pytest for core logic

2. Integration Tests: MCP protocol compliance testing

3. Smoke Tests: Quick validation of basic functionality

4. Evaluation Tests: LLM-based assessment of real-world usage

5. Performance Tests: Load and stress testing

Running MCP Evaluations

Docker Method (Recommended)

Due to potential permission issues with tsx, we recommend running MCP evaluations in Docker:

Direct Method (if permissions allow)

Docker Development

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📄 License

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

🔗 Related Projects

• Model Context Protocol

• MCP Example Servers

⭐ Support the Project

If you find this project helpful, please consider giving it a star on GitHub! Your support helps:

• 🚀 Increase visibility for other developers who might benefit from this tool

• 💪 Motivate continued development and maintenance

• 📈 Build community around the Model Context Protocol ecosystem

• 🛡️ Validate trust through community engagement

⭐ Star this repository — it takes just one click and means a lot!