Simplenote MCP Server

A FastMCP/FastAPI server that enables Claude Desktop to interact with Simplenote notes through the Model Context Protocol (MCP).

Features

• List, view, create, update, and trash Simplenote notes via MCP
• Search notes by content
• Filter notes by tags
• In-memory caching with background synchronization
• Bearer token authentication
• CORS support for Claude Desktop

Requirements

• Python 3.11+
• macOS 15+ (primary platform, but should work on others)
• Simplenote account
• uv package manager (for dependency installation)

Setup Instructions

1. Clone the Repository

git clone https://github.com/docdyhr/simplenote-mcp-server.git
cd simplenote-mcp-server

2. Create a Configuration File

Create a .env file in the root directory with the following variables:

SIMPLENOTE_EMAIL=your.email@example.com
SIMPLENOTE_PASSWORD=your_password
SERVER_PORT=8000
SERVER_AUTH_TOKEN=your_secure_token
SYNC_INTERVAL_SECONDS=120

# Rate limiting and timeout settings
DEFAULT_RATE_LIMIT="50/minute"
API_RATE_LIMIT="100/minute"
HEALTH_RATE_LIMIT="10/minute"
REQUEST_TIMEOUT_SECONDS=30

# Security settings - comma-separated list of allowed hosts (disabled by default)
# TRUSTED_HOSTS=localhost,127.0.0.1

Notes:

• SERVER_PORT defaults to 8000 if not specified
• SYNC_INTERVAL_SECONDS controls how frequently the server syncs with Simplenote (defaults to 60 seconds)
• Choose a strong, unique SERVER_AUTH_TOKEN as this will be used to authenticate Claude Desktop
• Rate limiting settings control the maximum number of requests per time period:
  • API_RATE_LIMIT: Applies to all API endpoints (default: 100/minute)
  • HEALTH_RATE_LIMIT: Applies to the health check endpoint (default: 10/minute)
  • DEFAULT_RATE_LIMIT: Default fallback rate limit (default: 50/minute)
• REQUEST_TIMEOUT_SECONDS: Maximum time in seconds a request can take before timing out (default: 30)
• TRUSTED_HOSTS: Optional comma-separated list of allowed hostnames for enhanced security

3. Install the uv Package Manager

If you don't already have uv installed:

# Using pip
pip install uv

# Or using homebrew on macOS
brew install uv

4. Run the Server

The included script handles creating a virtual environment, installing dependencies, and starting the server:

chmod +x run_server.sh
./run_server.sh

The server will start on the configured port (default: 8000).

Manual Setup (Alternative)

If you prefer to set up the environment manually:

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Configuring Claude Desktop

To configure Claude Desktop to use this MCP server:

1. In Claude Desktop, go to Settings > Model Context Protocol
2. Add a new MCP server with the following details:
   • URL: http://localhost:8000 (or your configured port)
   • Authentication: Bearer token
   • Token: The value you set for SERVER_AUTH_TOKEN
3. Save the configuration and enable the MCP server

API Endpoints

Health Check

• GET /health: Check if the server is running

MCP Discovery

• GET /api/v1/discovery: Lists all available tools and their schemas (used by Claude Desktop)

Tools

All tool endpoints use POST /api/v1/tools/{tool_name} with JSON request body

List Notes

• Endpoint: POST /api/v1/tools/list_notes
• Request: {} or {"tag": "tag-name"} to filter by tag
• Response: Array of note objects

Get Note

• Endpoint: POST /api/v1/tools/get_note
• Request: {"note_id": "string"}
• Response: Note object

Create Note

• Endpoint: POST /api/v1/tools/create_note
• Request: {"content": "string", "tags": ["string"]}
• Response: Created note object

Update Note

• Endpoint: POST /api/v1/tools/update_note
• Request: {"note_id": "string", "content": "string", "tags": ["string"]}
• Response: Updated note object

Trash Note

• Endpoint: POST /api/v1/tools/trash_note
• Request: {"note_id": "string"}
• Response: Boolean indicating success

Search Notes

• Endpoint: POST /api/v1/tools/search_notes
• Request: {"query": "string"}
• Response: Array of matching note objects

Note Object Schema

{
  "key": "string",
  "content": "string",
  "tags": ["string"],
  "createdate": "2024-01-01T12:00:00Z",
  "modifydate": "2024-01-02T15:30:00Z",
  "deleted": false,
  "systemtags": []
}

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run all tests
python -m pytest

# Run tests with coverage report
python -m pytest --cov=app

Troubleshooting

Connection Issues

• Verify the server is running on the expected port
• Check that your firewall allows connections to the port
• Ensure your Simplenote credentials are correct

Authentication Problems

• Verify that the SERVER_AUTH_TOKEN in your .env file matches the token configured in Claude Desktop
• Check the server logs for authentication errors

Syncing Issues

• If notes aren't appearing, try restarting the server to force a full sync
• Check server logs for any API errors

Security Notes

• Use HTTPS in production environments
• Keep your SERVER_AUTH_TOKEN secure
• Store sensitive credentials only in the .env file (never commit to version control)
• The server is designed for single-user use, not multi-tenant deployment
• Enable rate limiting to protect against abuse (configured via environment variables)
• Configure request timeouts to prevent long-running requests from consuming resources
• In production, enable the Trusted Hosts middleware by setting the TRUSTED_HOSTS environment variable

License

MIT