The Simplenote MCP Server integrates Simplenote with AI assistants (e.g., Claude Desktop), enabling comprehensive note management, advanced search, and more.
Note Operations: Create, read, update, soft-delete, permanently delete, restore, and empty trash notes.
Advanced Search: Full-text search with boolean operators, phrase matching, tag/date filters, fuzzy matching, pagination, and sorting by relevance, modification, or creation date.
Tag Management: Add, remove, replace, and rename tags across notes; list tags with note counts; find untagged notes.
Version History: Retrieve a note's version history and restore previous versions.
Content Manipulation: Append or prepend text, replace Markdown sections, and create/update daily notes with timestamped entries.
Bulk & Organizational Tools: Bulk tag notes, export to Markdown or JSON, find and merge duplicates, and atomically find-or-create notes by title.
Publishing: Publish notes to a public URL and unpublish them.
Client-side Encryption: Opt-in AES-256-GCM encryption for sensitive notes before they reach Simplenote.
Performance & Security: In-memory caching with background sync, token-based authentication, and security-hardened deployment options (Docker, Kubernetes/Helm, Smithery).
Server Information: Retrieve version, author, runtime debug info, and cache status.
Provides full note management capabilities including reading, creating, updating, and deleting notes, with advanced search features supporting boolean operators, phrase matching, tag and date filters.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Simplenote MCP Server search for notes about meeting agenda from last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: simplenote-mcp
30 Tools — Full Bear Parity + Simplenote Differentiators + Claude Companion Tools + Vault Encryption
Vault — opt-in client-side note encryption: Simplenote has no encryption at rest. create_note/update_note now accept encrypt: true, and encrypt_note/decrypt_note convert existing notes — bodies become AES-256-GCM ciphertext before they ever reach Simplenote's API. See docs/security/encryption-design.md.
MCP Resources and Prompts hardened for the working-memory companion use case:
Fixed: list_resources/read_resource were silently dropping tag/date/pagination metadata via non-schema fields — now attached through the MCP spec's _meta extension field, the correct mechanism.
session-handoff MCP Prompt: scaffolds the Session Continuity workflow (get_or_create_note + add_text with a Status:/Next:/Blockers: format) for cross-session context handoff.
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
1334 tests passing, 79%+ coverage, zero linting/type errors
See the CHANGELOG and ROADMAP.md for complete details.
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
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 for complete details.
📝 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
🔑 Vault Encryption: Opt-in client-side AES-256-GCM encryption for sensitive notes — Simplenote itself has no encryption at rest
🧩 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 1334 tests and continuous integration
🔒 Security Hardened: Regular security scanning with Bandit, pip-audit, and dependency checks
Simplenote account (create one at simplenote.com)
Python 3.10+ (for non-Docker installs) or Docker
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 \
-e MCP_TRANSPORT=http \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
-p 8000:8000 \
docdyhr/simplenote-mcp-server:latestMCP_HTTP_AUTH_TOKEN is required whenever MCP_HTTP_HOST is anything other
than 127.0.0.1/localhost — the server refuses to start otherwise (see the
Security section below). Without MCP_TRANSPORT=http, the server runs over
stdio by default and nothing listens on the published port at all.
Docker Health Checks: health monitoring is a separate HTTP endpoint
from the MCP protocol port above — it's off by default and must be enabled
explicitly with -e ENABLE_HTTP_ENDPOINT=true -e HTTP_HOST=0.0.0.0 -p 8080:8080
(Docker's -p mapping forwards to the container's network interface, not its
loopback, so HTTP_HOST must be 0.0.0.0 for the published port to actually
reach it — the 127.0.0.1 default only works if you're calling these
endpoints from another process inside the same container):
Health: http://localhost:8080/health
Readiness: http://localhost:8080/ready
Metrics: http://localhost:8080/metrics (Prometheus format)
The server refuses to start if HTTP_HOST is non-loopback and no
HTTP_ENDPOINT_AUTH_TOKEN is set, since these endpoints would otherwise be
reachable by anyone who can reach the port. Set a bearer token (checked via
Authorization: Bearer <token>, same mechanism as MCP_HTTP_AUTH_TOKEN
above) if you need a non-loopback bind — loopback callers are always
trusted regardless, so this never breaks a local health check. Prefer
keeping it loopback-only and publishing with -p 127.0.0.1:8080:8080
instead of -p 8080:8080 when you can.
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 -dInstall automatically via Smithery:
npx -y @smithery/cli install @docdyhr/simplenote-mcp-server --client claudeThis method automatically configures Claude Desktop with the MCP server.
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e .
simplenote-mcp-serverStart 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.
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
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 (see Quick Start above for the required MCP_HTTP_* env vars)
docker run -d \
-e SIMPLENOTE_EMAIL=your.email@example.com \
-e SIMPLENOTE_PASSWORD=your-password \
-e MCP_TRANSPORT=http \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
-p 8000:8000 \
docdyhr/simplenote-mcp-server:latest
# Or use Docker Compose (set MCP_HTTP_AUTH_TOKEN in your environment/.env first)
docker-compose up -dAvailable tags:
latest - Latest stable release
v1.18.0 - Specific version
main - Latest development build
# 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 \
-e MCP_TRANSPORT=http \
-e MCP_HTTP_HOST=0.0.0.0 \
-e MCP_HTTP_AUTH_TOKEN=your-random-secret-token \
-p 8000:8000 \
simplenote-mcp-server# Use the development compose file for live code mounting
docker-compose -f docker-compose.dev.yml upMulti-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
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"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
# values.yaml for production
replicaCount: 3
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10
resources:
limits:
cpu: 1000m
memory: 512Mi
requests:
cpu: 500m
memory: 256MiVariable | Required | Default | Description |
| Yes | - | Your Simplenote account email |
| Yes | - | Your Simplenote account password |
| No | 120 | Cache synchronization interval in seconds |
| No | 10000 | Max notes held in memory — set ≥ your total note count |
| No | INFO | Logging level (DEBUG, INFO, WARNING, ERROR) |
| No | false | Skip API calls; used for testing without credentials |
| No | stdio |
|
| No | 127.0.0.1 | Bind host when |
| Conditional | - | Bearer token; required if |
| No | - | Comma-separated allowlist for DNS-rebinding protection |
| No | - | Comma-separated Origin allowlist (used with the above) |
| No | false | Enable the separate |
| No | 127.0.0.1 | Bind host for the monitoring endpoint above |
| No | 8080 | Port for the monitoring endpoint above |
| Conditional | - | Bearer token; required if |
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"
}
}
}
}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 cancelledTool | Description | Parameters |
| Create a new note |
|
| Replace full note content (destructive) |
|
| Soft-delete: move note to Trash |
|
| Untrash a note — move it back from Trash |
|
| Irreversibly destroy a single note (requires |
|
| Permanently delete all trashed notes (dry-run by default) |
|
| Get a note by ID with full content and metadata |
|
| Append or prepend text without overwriting |
|
| Full-text search with filters and pagination |
|
| Add tags to a note |
|
| Remove specific tags from a note |
|
| Replace all tags on a note |
|
| List all tags with note counts |
|
| Rename a tag across all notes atomically |
|
| List version history for a note |
|
| Roll back a note to a previous version |
|
| Atomic find-or-create by title |
|
| Append a timestamped entry to today's note |
|
| Replace one Markdown section without touching others |
|
| Find notes with no tags |
|
| Apply tags to multiple notes in one call |
|
| Export notes to Markdown or JSON |
|
| Detect and merge duplicate notes |
|
| Server version, author, and runtime debug info | (no parameters) |
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
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
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
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
Status: ✅ WORKING - Complete mcp-evals integration with TypeScript wrapper!
This project includes comprehensive evaluations using mcp-evals to ensure reliability and performance:
# Setup evaluation environment
npm install
npm run validate:evals
# Run evaluation suites
npm run eval:smoke # Quick smoke tests (2-3 minutes) ✅ VERIFIED
npm run eval:basic # Standard evaluations (5-10 minutes)
npm run eval:comprehensive # Full evaluation suite (15-30 minutes)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)
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
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.
# Python unit tests
pytest
# Code quality checks
ruff check .
mypy simplenote_mcpToken-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
MCP HTTP transport is fail-closed by default: MCP_TRANSPORT=http
refuses to start on any non-loopback MCP_HTTP_HOST unless
MCP_HTTP_AUTH_TOKEN is set (a shared bearer secret, checked via
constant-time comparison). Loopback binds (127.0.0.1/localhost) work
without a token, matching stdio's local-process trust level. Set
MCP_HTTP_ALLOWED_HOSTS/MCP_HTTP_ALLOWED_ORIGINS (comma-separated) to
enable DNS-rebinding protection for non-loopback binds. This is intended
for private networks (behind a VPN/Tailscale/SSH tunnel) — a static
shared token has none of OAuth's revocation/audit/expiry properties, so
avoid exposing it directly to the public internet even with a token set.
Authentication Problems:
Verify SIMPLENOTE_EMAIL and SIMPLENOTE_PASSWORD are 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 --buildClaude Desktop Connection:
# Verify tools are available
./simplenote_mcp/scripts/verify_tools.sh
# Monitor logs
./simplenote_mcp/scripts/watch_logs.sh# 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# One-command setup including evaluations
./setup-dev-env-with-evals.sh
# Or manual setup
git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server
pip install -e ".[dev,test]"
npm install # For mcp-evals# Run the server
python simplenote_mcp_server.py
# Run Python tests
pytest
# Run mcp-evals
npm run eval:smoke # Quick validation
npm run eval:basic # Standard tests
npm run eval:all # Full test suite
# Code quality
ruff check .
ruff format .
mypy simplenote_mcpThe 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
Unit Tests: Traditional Python pytest for core logic
Integration Tests: MCP protocol compliance testing
Smoke Tests: Quick validation of basic functionality
Evaluation Tests: LLM-based assessment of real-world usage
Performance Tests: Load and stress testing
Due to potential permission issues with tsx, we recommend running MCP evaluations in Docker:
# Run smoke tests
./scripts/run-evals-docker.sh smoke
# Run basic evaluations
./scripts/run-evals-docker.sh basic
# Run comprehensive evaluations
./scripts/run-evals-docker.sh comprehensive
# Run all evaluations
./scripts/run-evals-docker.sh allnpm run eval:smoke
npm run eval:basic
npm run eval:comprehensive
npm run eval:all# 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 --helpContributions are welcome! Please read CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
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!
Export one or more notes to Markdown or JSON format
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Export format: 'markdown' (with YAML front matter) or 'json' (default: markdown) | |
| note_ids | Yes | Note IDs to export (comma-separated) | |
| include_metadata | No | Include metadata like dates, tags, and ID (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior; the description adds no further behavioral context beyond stating the export action, missing details like response format or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous words; purpose is front-loaded and directly stated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite full schema coverage, the description omits crucial context about the output behavior (e.g., whether the export is returned in the response or saved); no output schema exists to clarify.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions; the description does not add meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Export' and the resource 'notes' with specific formats 'Markdown or JSON', differentiating it from sibling tools like get_note or list_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as get_note or search_notes; no prerequisites or context for usage provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes that have no tags. Useful for tag housekeeping — find notes that need to be organized.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of notes to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds no behavioral context beyond that, but does not contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description adequately covers purpose and use case. Missing details like sorting or pagination are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter description. The tool description adds no additional parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List notes that have no tags') with a clear verb and resource. It distinguishes from sibling tools like list_notes and search_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context ('Useful for tag housekeeping — find notes that need to be organized') that implies when to use, though no explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the full content of a note by ID from Simplenote. Use search_notes when you don't know the exact note ID.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | The ID of the note to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as readOnly, idempotent, openWorld, and non-destructive. The description does not add extra context beyond what annotations provide, such as rate limits, response format, or content limits. Score is baseline as annotations cover safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, each valuable and front-loaded. No wasted words, making it highly efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter), rich annotations, and clear sibling differentiation, the description is nearly complete. No output schema exists, but the return value (full content) is implied. A minor gap is lack of details on what 'full content' includes (e.g., formatting, size limits).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of note_id. The tool description does not add additional meaning or constraints beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'full content of a note by ID from Simplenote', which is a specific verb and resource. It also distinguishes from sibling search_notes, meeting the highest standard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides guidance on when to use this tool vs. alternatives: 'Use search_notes when you don't know the exact note ID.' This is a clear usage directive with an alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve the version history of a note (up to 10 most recent versions).
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes | The ID of the note |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already declare safety traits. The description adds the critical behavioral detail that only up to 10 versions are returned, going beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the verb and key constraint. Every word contributes meaning; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and no output schema, the description is adequate but lacks detail about return format, ordering, or error cases (e.g., what if note has fewer than 10 versions). It is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter note_id, which has a clear description. The tool description adds no additional parameter insight, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('version history of a note'), and includes a specific constraint ('up to 10 most recent versions'). This differentiates it from siblings like get_note or search_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when needing version history) but provides no explicit guidance on when not to use it or alternatives. No exclusions or comparisons to siblings are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return version, author, and debug information about this MCP server. Use this to confirm which version is running, check whether the cache is initialized, and see runtime settings (log level, sync interval, offline mode). No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; the description adds specifics about the returned data (version, author, debug info, cache, runtime settings). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the core purpose, the second elaborates on use cases. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description enumerates the types of information returned (version, author, debug, cache status, runtime settings). This covers all necessary context for a parameterless info tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters are present, and schema coverage is 100%. Per rubric, baseline 4 is appropriate as the description doesn't need to add param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns version, author, and debug information about the MCP server, specifying concrete use cases like confirming version, checking cache initialization, and viewing runtime settings. It is distinct from sibling tools that deal with notes and tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use it (to confirm version, check cache, see settings). While it doesn't state when not to use it, the context is clear and no alternatives are relevant among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent notes, optionally filtered by tag. Use search_notes for full-text or boolean queries. Use list_tags first to discover available tag names.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by tag name (exact match) | |
| limit | No | Maximum number of notes to return (default: 20, max: 100) | |
| include_deleted | No | Include trashed notes (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint, destructiveHint false, and idempotentHint. The description adds minor context (optionally filtered, order by recency) but does not explain what 'recent' means or describe return format, leaving some behavioral ambiguity. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and includes relevant usage guidance without extraneous detail. Every word is necessary and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description provides sufficient context for usage: it explains the basic operation, optional filter, and links to related tools. Minor gaps about ordering and return format are acceptable given the tool's simplicity and the presence of strong annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description. The description confirms optional tag filtering but does not add substantial new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List recent notes' with optional tag filtering. It distinguishes from sibling tools by explicitly mentioning 'Use search_notes for full-text or boolean queries' and suggests using list_tags first, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it tells the agent to use search_notes for different query types and to use list_tags to discover available tag names, clearly outlining when this tool is appropriate vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tags used across notes with note counts. Use this before creating or searching by tags to discover existing tags and avoid fragmentation.
| Name | Required | Description | Default |
|---|---|---|---|
| sort_by | No | Sort order: 'alpha' (alphabetical, default) or 'count' (by note count descending) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims to list 'all tags', but the openWorldHint annotation indicates the output may not be exhaustive. This contradiction makes the description misleading regarding behavior. Additionally, no further behavioral details (e.g., rate limits, auth) are disclosed beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one stating the core function, the other providing usage advice. No extraneous information, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and includes note counts, but lacks details on output structure (e.g., format of tags and counts) and pagination behavior. Given the absence of output schema and the openWorldHint, some completeness is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single optional parameter fully described in the schema. The description adds no extra meaning beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all tags with note counts, and advises using it before creating or searching by tags to avoid fragmentation, effectively distinguishing it from sibling tools like list_notes or search_notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use the tool ('Use this before creating or searching by tags') and implies when not to use it (when tags are already known), providing clear context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for notes in Simplenote with advanced capabilities including fuzzy matching, pagination, and sorting support. To find the most recently updated note on a topic, use sort_by='modifydate' with sort_direction='desc' and limit=1. Use list_tags first if you need to discover available tags before filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags to filter by — all must be present (array of strings; a comma-separated string is also accepted). Use 'untagged' to find notes without tags. | |
| fuzzy | No | Enable fuzzy matching to handle typos and approximate matches (default: false) | |
| limit | No | Maximum number of results to return per page (default: 20) | |
| query | Yes | The search query (supports boolean operators AND, OR, NOT; phrase matching with quotes; tag filters like tag:work; date filters like from:2023-01-01 to:2023-12-31 or natural language dates like from:last_week to:yesterday) | |
| offset | No | Number of results to skip for pagination (default: 0) | |
| pinned | No | Filter by pin status: true = only pinned notes, false = only unpinned notes, omit = all notes | |
| sort_by | No | Sort results by field. Default: 'relevance' (by match quality). Use 'modifydate' to get the most recently updated notes first. Use 'createdate' to get the newest-created notes first. | |
| to_date | No | Filter notes modified before this date (ISO format e.g. 2023-12-31, or natural language e.g. today, yesterday) | |
| from_date | No | Filter notes modified after this date (ISO format e.g. 2023-01-01, or natural language e.g. yesterday, last_week, 3_days_ago) | |
| created_after | No | Filter notes created after this date (ISO format e.g. 2023-01-01) | |
| modified_after | No | Filter notes modified after this date (ISO format e.g. 2023-06-01) | |
| sort_direction | No | Sort direction: 'desc' (newest/highest first, default) or 'asc' (oldest/lowest first). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and idempotent. The description adds valuable behavioral context: supports fuzzy matching, boolean operators, phrase matching, natural language dates, and sorted results. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: first sentence states purpose, second gives a practical tip, third suggests a complementary tool. No redundant information, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, 100% schema coverage, and no output schema, the description covers search behavior, filtering, sorting, and pagination. It could mention the return format (likely a list of note summaries) but overall is sufficiently complete for an optimized tool description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds extra meaning by providing usage context (e.g., natural language dates, sort_by examples) and cross-referencing list_tags. However, most parameters are already well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search for notes in Simplenote with advanced capabilities including...' which clearly identifies the tool's action (search) and resource (notes). It distinguishes from siblings like list_notes (full listing) and find_untagged_notes by specifying advanced search features.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage examples: 'To find the most recently updated note on a topic, use sort_by='modifydate'...' and advises using list_tags for tag discovery. This guides the agent on when and how to use the tool effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the Vault encryption key status: whether a key is available this session, which provider it came from (keyring or SIMPLENOTE_VAULT_KEY_FILE), and how many notes are currently Vault-encrypted. Call this before encrypt_note/decrypt_note or create_note/update_note with encrypt=true if you're unsure whether a key is provisioned. No parameters required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds specific context about the returned status details (key availability, provider, encrypted note count), which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences, front-loaded with the purpose and key details. Every sentence adds value without redundancy or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and rich annotations, the description fully covers what the tool does, when to use it, and what it returns. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters; baseline is 4 per guidelines. No additional parameter information is needed, and description correctly states 'No parameters required.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Check the Vault encryption key status' and lists specific elements returned (key availability, provider, number of encrypted notes). It precisely identifies the tool's function and distinguishes it from sibling tools like get_server_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to call the tool: before encrypt_note/decrypt_note or create_note/update_note with encrypt=true if unsure about key provisioning. Also notes 'No parameters required,' reducing ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.17.2search_notes3 fields changedInput schema / properties / tags / descriptionPrevious value: -"Tags to filter by (comma-separated list of tags that must all be present). Use 'untagged' to find notes without tags."New value: +"Tags to filter by — all must be present (array of strings; a comma-separated string is also accepted). Use 'untagged' to find notes without tags."Input schema / properties / tags / itemsAdded value: +{
+ "type": "string"
+}Input schema / properties / tags / typePrevious value: -"string"New value: +"array"vault_statusv1.0.0export_notesfind_untagged_notesget_noteget_note_versionsget_server_infolist_noteslist_tagssearch_notesEach tool has a clearly distinct purpose: export, find untagged, get by ID, get versions, server info, list notes, list tags, search, and vault status. No two tools overlap in functionality.
All tool names follow a consistent snake_case verb_noun pattern (e.g., export_notes, list_tags, get_note). Even 'vault_status' is noun_verb but fits the style. No mixing of conventions.
9 tools is a reasonable count for a note-taking server, though the set lacks core CRUD operations. The number itself is appropriate for the scope, but slightly incomplete.
The tool set is missing essential note operations: create, update, delete, and encrypt/decrypt. References in vault_status imply they exist but aren't provided, leaving significant gaps for typical workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Search, read, create and edit your Memol notes from Claude. Team note-taking with AI search.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/docdyhr/simplenote-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
