Content
# Yinxiang MCP Server
Built on top of the Evernote Developer API, this MCP (Model Context Protocol) Server enables Claude to directly interact with your Evernote account.
## Features
| Tool | Functionality |
|------|--------------|
| `yinxiang_list_notebooks` | List all notebooks (including GUID) |
| `yinxiang_list_notes` | List notes, supporting filtering by notebook and pagination |
| `yinxiang_search_notes` | Full-text search notes (supporting Evernote search syntax) |
| `yinxiang_get_note` | Retrieve the complete content of a specified note |
| `yinxiang_create_note` | Create a new note (Markdown → ENML automatic conversion) |
| `yinxiang_update_note` | Update a note's title or content |
## Quick Start
### Step 1: Obtain Developer Token
1. Visit https://app.yinxiang.com/api/DeveloperToken.action
2. Click "Create a developer token"
3. Copy the token starting with `S=s1:`, and fill it into the `.env` file
### Step 2: Install Dependencies
```bash
cd ~/mcp-servers/yinxiang-mcp
uv venv --python 3.11
uv pip install -r requirements.txt
```
### Step 3: Start HTTP Server
```bash
./start.sh # Start in the background (port 8765)
./status.sh # Check status
./stop.sh # Stop the service
```
### Step 4 (Optional): Autostart on Boot
```bash
cp com.yinxiang.mcp.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.yinxiang.mcp.plist
```
## Connect to MCP Client
After the server starts, all MCP-supported clients can connect through the following endpoint:
```
http://127.0.0.1:8765/mcp
```
### Claude Code
Add the following to `~/.claude/settings.json`:
```json
"yinxiang": {
"url": "http://127.0.0.1:8765/mcp"
}
```
### CatPaw / Other MCP Clients
In the client's MCP configuration, fill in:
- **Type**: Streamable HTTP
- **URL**: `http://127.0.0.1:8765/mcp`
## Search Syntax
Evernote supports rich search syntax:
| Syntax | Example | Description |
|------|--------|------------|
| Keywords | `Python learning` | Full-text search |
| `notebook:` | `notebook:Work` | By notebook name |
| `tag:` | `tag:Important` | By tag |
| `intitle:` | `intitle:Meeting Minutes` | By title keywords |
| `created:` | `created:20240601` | By creation date |
| `updated:` | `updated:20240101` | By update date |
| Combined | `tag:Work intitle:Weekly Report` | Multi-condition combination |
## Precautions
- **Token Security**: The Developer Token has full account access permissions, please keep it secure and do not submit it to the code repository.
- **API Rate Limiting**: Evernote limits the number of API calls per user per hour, normal personal use will not trigger this limit.
- **ENML Format**: Note content uses ENML (Evernote XML format), the tool will automatically complete Markdown ↔ ENML conversion.
- **China Version Only**: This server configuration is for the Chinese version of Evernote (app.yinxiang.com), not compatible with the international version of Evernote.
## For AI Agents / Automated Installation Guide
If a user asks you to install this MCP server, please follow these EXACT steps strictly:
1. **Clone & Setup Environment**:
Clone the repository to a suitable location. Create a Python 3.11+ virtual environment (`python -m venv .venv` or `uv venv`) and install dependencies from `requirements.txt`.
2. **Ask for Developer Token (CRITICAL)**:
You CANNOT generate the Evernote/Yinxiang developer token for the user. You MUST pause and ask the user to provide it.
Provide them this exact link: `https://app.yinxiang.com/api/DeveloperToken.action`
Wait for their reply with the token (starting with `S=s...`).
3. **Configure MCP Client (Use stdio mode)**:
Once you have the token, DO NOT use the HTTP mode or `start.sh`. Configure the user's IDE/MCP Client using the `stdio` transport.
Set the configuration as follows:
- Command: `/path/to/repo/.venv/bin/python` (use the absolute path to the venv python)
- Arguments: `["/path/to/repo/server.py"]` (absolute path)
- Environment Variables: `{"YINXIANG_TOKEN": "the_token_user_provided"}`
4. **Verify**:
Inform the user that the installation is complete and the MCP is registered via `stdio`.
