joplin-mcp

Name	joplin-mcp JSON
Version	0.3.1 JSON
	download
home_page	None
Summary	Model Context Protocol (MCP) server for Joplin note-taking application
upload_time	2025-08-01 02:18:45
maintainer	Alon Diament
docs_url	None
author	Alon Diament
requires_python	>=3.8
license	MIT License Copyright (c) 2025 Alon Diament Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	joplin mcp model-context-protocol notes ai assistant
VCS
bugtrack_url
requirements	mcp joppy fastmcp pydantic httpx typing-extensions PyYAML pytest pytest-asyncio pytest-mock coverage black ruff mypy pre-commit
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Joplin MCP Server

A **FastMCP-based Model Context Protocol (MCP) server** for [Joplin](https://joplinapp.org/) note-taking application via its Python API [joppy](https://github.com/marph91/joppy), enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.

## Table of Contents

- [What You Can Do](#what-you-can-do)
- [Quick Start](#quick-start)
- [Example Usage](#example-usage)
- [Tool Permissions](#tool-permissions)
- [Advanced Configuration](#advanced-configuration)
- [Project Structure](#project-structure)
- [Testing](#testing)
- [Complete Tool Reference](#complete-tool-reference)
- [Changelog](CHANGELOG.md)

## What You Can Do

This MCP server provides **21 optimized tools** for comprehensive Joplin integration:

### **Note Management**
- **Find & Search**: `find_notes`, `find_notes_with_tag`, `find_notes_in_notebook`, `get_all_notes`
- **CRUD Operations**: `get_note`, `get_links`, `create_note`, `update_note`, `delete_note`

### **Notebook Management** 
- **Organize**: `list_notebooks`, `create_notebook`, `update_notebook`, `delete_notebook`

### **Tag Management**
- **Categorize**: `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `get_tags_by_note`
- **Link**: `tag_note`, `untag_note`

### **System**
- **Health**: `ping_joplin`

## Quick Start


### 1. Configure Joplin

1. Open **Joplin Desktop** → **Tools** → **Options** → **Web Clipper**
2. **Enable** the Web Clipper service
3. **Copy** the Authorization token

### 2. Choose Your AI Client

#### Option A: Claude Desktop (Automated Setup)

Run the automated installer:

```bash
# Install and configure everything automatically
uvx joplin-mcp-install
```

This script will:
- Configure your Joplin API token  
- Set tool permissions (Create/Update/Delete)
- Set up Claude Desktop automatically
- Test the connection

After setup, restart Claude Desktop and you're ready to go!

```
"List my notebooks" or "Create a note about today's meeting"
```

#### Option B: Jan AI

**B1: Manual Setup (Recommended - Simplest)**

1. **Install Jan AI** from [https://jan.ai](https://jan.ai)

2. **Add MCP Server** in Jan's interface:
   - Open Jan AI
   - Go to **Settings** → **Extensions** → **Model Context Protocol**
   - Click **Add MCP Server**
   - Configure:
     - **Name**: `joplin`
     - **Command**: `uvx joplin-mcp`
     - **Environment Variables**:
       - `JOPLIN_TOKEN`: `your_joplin_api_token_here`
   - Enable the server

3. **Start chatting** with access to your Joplin notes!

**B2: Automated Setup (Alternative)**

```bash
# Install and configure Jan AI automatically (if Jan is already installed)
uvx joplin-mcp-install
```

This will detect and configure Jan AI automatically, just like Claude Desktop.

```
"Show me my recent notes" or "Create a project planning note"
```

#### Option C: OllMCP (Local AI Models)

For local Ollama models:

**Option C1: Auto-discovery (if you set up Claude Desktop first)**
```bash
# Install ollmcp
pip install ollmcp

# Run with auto-discovery (requires existing Claude Desktop config)
ollmcp --auto-discovery --model qwen3:4b
```

**Option C2: Manual setup (works independently)**
```bash
# Install ollmcp
pip install ollmcp

# Set environment variable
export JOPLIN_TOKEN="your_joplin_api_token_here"

# Run with manual server configuration
ollmcp --server "joplin:uvx joplin-mcp" --model qwen3:4b
```

## Example Usage

Once configured, you can ask your AI assistant:

- **"List all my notebooks"** - See your Joplin organization
- **"Find notes about Python programming"** - Search your knowledge base  
- **"Create a meeting note for today's standup"** - Quick note creation
- **"Tag my recent AI notes as 'important'"** - Organize with tags
- **"Show me my todos"** - Find task items with `find_notes(task=True)`

## Tool Permissions

The setup script offers **3 security levels**:

- **Read** (always enabled): Browse and search your notes safely
- **Write** (optional): Create new notes, notebooks, and tags  
- **Update** (optional): Modify existing content
- **Delete** (optional): Remove content permanently

Choose the level that matches your comfort and use case.

---

## Advanced Configuration

### Alternative Installation Methods

#### Method 1: Traditional pip install

If you don't have `uvx` or prefer to customize MCP settings:

```bash
# Install the package
pip install joplin-mcp

# Run the setup script
joplin-mcp-install
```

This method provides the same functionality as `uvx joplin-mcp-install` but requires a local Python environment.

#### Method 2: Development Installation

For developers or users who want the latest features:

**macOS/Linux:**
```bash
git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
./install.sh
```

**Windows:**
```batch
git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
install.bat
```

### Manual Configuration

If you prefer manual setup or the script doesn't work:

> **Note**: `uvx` is a tool for running Python applications in isolated environments without permanent installation. If you don't have it, install with `pip install uv` or use the "installed package" options below.

#### 1. Create Configuration File

Create `joplin-mcp.json` in your project directory:

```json
{
  "token": "your_api_token_here",
  "host": "localhost", 
  "port": 41184,
  "timeout": 30,
  "verify_ssl": false
}
```

#### 2. Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

**Option A: Using uvx (Recommended)**
```json
{
  "mcpServers": {
    "joplin": {
      "command": "uvx",
      "args": ["joplin-mcp"],
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}
```

**Option B: Using installed package**
```json
{
  "mcpServers": {
    "joplin": {
      "command": "joplin-mcp-server",
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}
```

#### 3. OllMCP Manual Configuration

**Option A: Using uvx (Recommended)**
```bash
# Set environment variable
export JOPLIN_TOKEN="your_token_here"

# Run with manual server configuration
ollmcp --server "joplin:uvx joplin-mcp" --model qwen3:4b
```

**Option B: Using installed package**
```bash
# Set environment variable
export JOPLIN_TOKEN="your_token_here"

# Run with manual server configuration
ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b
```

#### 4. More Client Configuration Examples

For additional client configurations including different transport options (HTTP, SSE, Streamable HTTP), see [client-config.json.example](client-config.json.example).

This file includes configurations for:
- **STDIO transport** (default, most compatible)
- **HTTP transport** (basic HTTP server mode)
- **SSE transport** (recommended for gemini-cli and OpenAI clients)
- **Streamable HTTP transport** (advanced web clients)

### Tool Permission Configuration

Fine-tune which operations the AI can perform by editing your config:

```json
{
  "tools": {
    "create_note": true,
    "update_note": true, 
    "delete_note": false,
    "create_notebook": true,
    "delete_notebook": false,
    "create_tag": true,
    "update_tag": false,
    "delete_tag": false
  }
}
```

### Environment Variables

Alternative to JSON configuration:

```bash
export JOPLIN_TOKEN="your_api_token_here"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"
```

### HTTP Transport Support

The server supports both STDIO and HTTP transports:

```bash
# STDIO (default)
joplin-mcp-server

# HTTP transport 
python run_fastmcp_server.py --transport http --port 8000
```

# Claude Desktop HTTP config
```json
{
  "mcpServers": {
    "joplin": {
      "transport": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

### Configuration Reference

#### Basic Settings
| Option | Default | Description |
|--------|---------|-------------|
| `token` | *required* | Joplin API authentication token |
| `host` | `localhost` | Joplin server hostname |
| `port` | `41184` | Joplin Web Clipper port |
| `timeout` | `30` | Request timeout in seconds |
| `verify_ssl` | `false` | SSL certificate verification |

#### Tool Permissions
| Option | Default | Description |
|--------|---------|-------------|
| `tools.create_note` | `true` | Allow creating new notes |
| `tools.update_note` | `true` | Allow modifying existing notes |
| `tools.delete_note` | `true` | Allow deleting notes |
| `tools.create_notebook` | `true` | Allow creating new notebooks |
| `tools.update_notebook` | `false` | Allow modifying notebook titles |
| `tools.delete_notebook` | `true` | Allow deleting notebooks |
| `tools.create_tag` | `true` | Allow creating new tags |
| `tools.update_tag` | `false` | Allow modifying tag titles |
| `tools.delete_tag` | `true` | Allow deleting tags |
| `tools.tag_note` | `true` | Allow adding tags to notes |
| `tools.untag_note` | `true` | Allow removing tags from notes |
| `tools.find_notes` | `true` | Allow text search across notes (with task filtering) |
| `tools.find_notes_with_tag` | `true` | Allow finding notes by tag (with task filtering) |
| `tools.find_notes_in_notebook` | `true` | Allow finding notes by notebook (with task filtering) |
| `tools.get_all_notes` | `false` | Allow getting all notes (disabled by default - can fill context window) |
| `tools.get_note` | `true` | Allow getting specific notes |
| `tools.list_notebooks` | `true` | Allow listing all notebooks |
| `tools.list_tags` | `true` | Allow listing all tags |
| `tools.get_tags_by_note` | `true` | Allow getting tags for specific notes |
| `tools.ping_joplin` | `true` | Allow testing server connectivity |

#### Content Exposure (Privacy Settings)
| Option | Default | Description |
|--------|---------|-------------|
| `content_exposure.search_results` | `"preview"` | Content visibility in search results: `"none"`, `"preview"`, `"full"` |
| `content_exposure.individual_notes` | `"full"` | Content visibility for individual notes: `"none"`, `"preview"`, `"full"` |
| `content_exposure.listings` | `"none"` | Content visibility in note listings: `"none"`, `"preview"`, `"full"` |
| `content_exposure.max_preview_length` | `300` | Maximum length of content previews (characters) |

## Project Structure

- **`run_fastmcp_server.py`** - FastMCP server launcher
- **`src/joplin_mcp/`** - Main package directory
  - `fastmcp_server.py` - Server implementation with 21 tools and Pydantic validation types
  - `config.py` - Configuration management
  - `server.py` - Legacy server implementation  
  - `ui_integration.py` - UI integration utilities
- **`docs/`** - Documentation (troubleshooting, privacy controls, enhancement proposals)
- **`tests/`** - Test suite

## Testing

Test your connection:

```bash
# For pip install
joplin-mcp-server

# For development  
python run_fastmcp_server.py
```

You should see:
```
Starting Joplin FastMCP Server...
Successfully connected to Joplin!
Found X notebooks, Y notes, Z tags
FastMCP server starting...
Available tools: 21 tools ready
```

## Complete Tool Reference

| Tool | Permission | Description |
|------|------------|-------------|
| **Finding Notes** | | |
| `find_notes` | Read | Full-text search across all notes (supports task filtering) |
| `find_notes_with_tag` | Read | Find notes with specific tag (supports task filtering) |
| `find_notes_in_notebook` | Read | Find notes in specific notebook (supports task filtering) |
| `get_all_notes` | Read | Get all notes, most recent first *(disabled by default)* |
| `get_note` | Read | Get specific note by ID |
| `get_links` | Read | Extract links to other notes from a note |
| **Managing Notes** | | |
| `create_note` | Write | Create new notes |
| `update_note` | Update | Modify existing notes |
| `delete_note` | Delete | Remove notes |
| **Managing Notebooks** | | |
| `list_notebooks` | Read | Browse all notebooks |
| `create_notebook` | Write | Create new notebooks |
| `update_notebook` | Update | Modify notebook titles |
| `delete_notebook` | Delete | Remove notebooks |
| **Managing Tags** | | |
| `list_tags` | Read | View all available tags |
| `create_tag` | Write | Create new tags |
| `update_tag` | Update | Modify tag titles |
| `delete_tag` | Delete | Remove tags |
| `get_tags_by_note` | Read | List tags on specific note |
| **Tag-Note Relationships** | | |
| `tag_note` | Update | Add tags to notes |
| `untag_note` | Update | Remove tags from notes |
| **System Tools** | | |
| `ping_joplin` | Read | Test connectivity |

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "joplin-mcp",
    "maintainer": "Alon Diament",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "joplin, mcp, model-context-protocol, notes, ai, assistant",
    "author": "Alon Diament",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/f1/0a/c3cd1172c658ef8bf5cbd6ae3693c1d3bdeaf183bcd73363589edd8424ab/joplin_mcp-0.3.1.tar.gz",
    "platform": null,
    "description": "# Joplin MCP Server\n\nA **FastMCP-based Model Context Protocol (MCP) server** for [Joplin](https://joplinapp.org/) note-taking application via its Python API [joppy](https://github.com/marph91/joppy), enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.\n\n## Table of Contents\n\n- [What You Can Do](#what-you-can-do)\n- [Quick Start](#quick-start)\n- [Example Usage](#example-usage)\n- [Tool Permissions](#tool-permissions)\n- [Advanced Configuration](#advanced-configuration)\n- [Project Structure](#project-structure)\n- [Testing](#testing)\n- [Complete Tool Reference](#complete-tool-reference)\n- [Changelog](CHANGELOG.md)\n\n## What You Can Do\n\nThis MCP server provides **21 optimized tools** for comprehensive Joplin integration:\n\n### **Note Management**\n- **Find & Search**: `find_notes`, `find_notes_with_tag`, `find_notes_in_notebook`, `get_all_notes`\n- **CRUD Operations**: `get_note`, `get_links`, `create_note`, `update_note`, `delete_note`\n\n### **Notebook Management** \n- **Organize**: `list_notebooks`, `create_notebook`, `update_notebook`, `delete_notebook`\n\n### **Tag Management**\n- **Categorize**: `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `get_tags_by_note`\n- **Link**: `tag_note`, `untag_note`\n\n### **System**\n- **Health**: `ping_joplin`\n\n## Quick Start\n\n\n### 1. Configure Joplin\n\n1. Open **Joplin Desktop** \u2192 **Tools** \u2192 **Options** \u2192 **Web Clipper**\n2. **Enable** the Web Clipper service\n3. **Copy** the Authorization token\n\n### 2. Choose Your AI Client\n\n#### Option A: Claude Desktop (Automated Setup)\n\nRun the automated installer:\n\n```bash\n# Install and configure everything automatically\nuvx joplin-mcp-install\n```\n\nThis script will:\n- Configure your Joplin API token  \n- Set tool permissions (Create/Update/Delete)\n- Set up Claude Desktop automatically\n- Test the connection\n\nAfter setup, restart Claude Desktop and you're ready to go!\n\n```\n\"List my notebooks\" or \"Create a note about today's meeting\"\n```\n\n#### Option B: Jan AI\n\n**B1: Manual Setup (Recommended - Simplest)**\n\n1. **Install Jan AI** from [https://jan.ai](https://jan.ai)\n\n2. **Add MCP Server** in Jan's interface:\n   - Open Jan AI\n   - Go to **Settings** \u2192 **Extensions** \u2192 **Model Context Protocol**\n   - Click **Add MCP Server**\n   - Configure:\n     - **Name**: `joplin`\n     - **Command**: `uvx joplin-mcp`\n     - **Environment Variables**:\n       - `JOPLIN_TOKEN`: `your_joplin_api_token_here`\n   - Enable the server\n\n3. **Start chatting** with access to your Joplin notes!\n\n**B2: Automated Setup (Alternative)**\n\n```bash\n# Install and configure Jan AI automatically (if Jan is already installed)\nuvx joplin-mcp-install\n```\n\nThis will detect and configure Jan AI automatically, just like Claude Desktop.\n\n```\n\"Show me my recent notes\" or \"Create a project planning note\"\n```\n\n#### Option C: OllMCP (Local AI Models)\n\nFor local Ollama models:\n\n**Option C1: Auto-discovery (if you set up Claude Desktop first)**\n```bash\n# Install ollmcp\npip install ollmcp\n\n# Run with auto-discovery (requires existing Claude Desktop config)\nollmcp --auto-discovery --model qwen3:4b\n```\n\n**Option C2: Manual setup (works independently)**\n```bash\n# Install ollmcp\npip install ollmcp\n\n# Set environment variable\nexport JOPLIN_TOKEN=\"your_joplin_api_token_here\"\n\n# Run with manual server configuration\nollmcp --server \"joplin:uvx joplin-mcp\" --model qwen3:4b\n```\n\n## Example Usage\n\nOnce configured, you can ask your AI assistant:\n\n- **\"List all my notebooks\"** - See your Joplin organization\n- **\"Find notes about Python programming\"** - Search your knowledge base  \n- **\"Create a meeting note for today's standup\"** - Quick note creation\n- **\"Tag my recent AI notes as 'important'\"** - Organize with tags\n- **\"Show me my todos\"** - Find task items with `find_notes(task=True)`\n\n## Tool Permissions\n\nThe setup script offers **3 security levels**:\n\n- **Read** (always enabled): Browse and search your notes safely\n- **Write** (optional): Create new notes, notebooks, and tags  \n- **Update** (optional): Modify existing content\n- **Delete** (optional): Remove content permanently\n\nChoose the level that matches your comfort and use case.\n\n---\n\n## Advanced Configuration\n\n### Alternative Installation Methods\n\n#### Method 1: Traditional pip install\n\nIf you don't have `uvx` or prefer to customize MCP settings:\n\n```bash\n# Install the package\npip install joplin-mcp\n\n# Run the setup script\njoplin-mcp-install\n```\n\nThis method provides the same functionality as `uvx joplin-mcp-install` but requires a local Python environment.\n\n#### Method 2: Development Installation\n\nFor developers or users who want the latest features:\n\n**macOS/Linux:**\n```bash\ngit clone https://github.com/alondmnt/joplin-mcp.git\ncd joplin-mcp\n./install.sh\n```\n\n**Windows:**\n```batch\ngit clone https://github.com/alondmnt/joplin-mcp.git\ncd joplin-mcp\ninstall.bat\n```\n\n### Manual Configuration\n\nIf you prefer manual setup or the script doesn't work:\n\n> **Note**: `uvx` is a tool for running Python applications in isolated environments without permanent installation. If you don't have it, install with `pip install uv` or use the \"installed package\" options below.\n\n#### 1. Create Configuration File\n\nCreate `joplin-mcp.json` in your project directory:\n\n```json\n{\n  \"token\": \"your_api_token_here\",\n  \"host\": \"localhost\", \n  \"port\": 41184,\n  \"timeout\": 30,\n  \"verify_ssl\": false\n}\n```\n\n#### 2. Claude Desktop Configuration\n\nAdd to your `claude_desktop_config.json`:\n\n**Option A: Using uvx (Recommended)**\n```json\n{\n  \"mcpServers\": {\n    \"joplin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"joplin-mcp\"],\n      \"env\": {\n        \"JOPLIN_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n**Option B: Using installed package**\n```json\n{\n  \"mcpServers\": {\n    \"joplin\": {\n      \"command\": \"joplin-mcp-server\",\n      \"env\": {\n        \"JOPLIN_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\n#### 3. OllMCP Manual Configuration\n\n**Option A: Using uvx (Recommended)**\n```bash\n# Set environment variable\nexport JOPLIN_TOKEN=\"your_token_here\"\n\n# Run with manual server configuration\nollmcp --server \"joplin:uvx joplin-mcp\" --model qwen3:4b\n```\n\n**Option B: Using installed package**\n```bash\n# Set environment variable\nexport JOPLIN_TOKEN=\"your_token_here\"\n\n# Run with manual server configuration\nollmcp --server \"joplin:joplin-mcp-server\" --model qwen3:4b\n```\n\n#### 4. More Client Configuration Examples\n\nFor additional client configurations including different transport options (HTTP, SSE, Streamable HTTP), see [client-config.json.example](client-config.json.example).\n\nThis file includes configurations for:\n- **STDIO transport** (default, most compatible)\n- **HTTP transport** (basic HTTP server mode)\n- **SSE transport** (recommended for gemini-cli and OpenAI clients)\n- **Streamable HTTP transport** (advanced web clients)\n\n### Tool Permission Configuration\n\nFine-tune which operations the AI can perform by editing your config:\n\n```json\n{\n  \"tools\": {\n    \"create_note\": true,\n    \"update_note\": true, \n    \"delete_note\": false,\n    \"create_notebook\": true,\n    \"delete_notebook\": false,\n    \"create_tag\": true,\n    \"update_tag\": false,\n    \"delete_tag\": false\n  }\n}\n```\n\n### Environment Variables\n\nAlternative to JSON configuration:\n\n```bash\nexport JOPLIN_TOKEN=\"your_api_token_here\"\nexport JOPLIN_HOST=\"localhost\"\nexport JOPLIN_PORT=\"41184\"\nexport JOPLIN_TIMEOUT=\"30\"\n```\n\n### HTTP Transport Support\n\nThe server supports both STDIO and HTTP transports:\n\n```bash\n# STDIO (default)\njoplin-mcp-server\n\n# HTTP transport \npython run_fastmcp_server.py --transport http --port 8000\n```\n\n# Claude Desktop HTTP config\n```json\n{\n  \"mcpServers\": {\n    \"joplin\": {\n      \"transport\": \"http\",\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### Configuration Reference\n\n#### Basic Settings\n| Option | Default | Description |\n|--------|---------|-------------|\n| `token` | *required* | Joplin API authentication token |\n| `host` | `localhost` | Joplin server hostname |\n| `port` | `41184` | Joplin Web Clipper port |\n| `timeout` | `30` | Request timeout in seconds |\n| `verify_ssl` | `false` | SSL certificate verification |\n\n#### Tool Permissions\n| Option | Default | Description |\n|--------|---------|-------------|\n| `tools.create_note` | `true` | Allow creating new notes |\n| `tools.update_note` | `true` | Allow modifying existing notes |\n| `tools.delete_note` | `true` | Allow deleting notes |\n| `tools.create_notebook` | `true` | Allow creating new notebooks |\n| `tools.update_notebook` | `false` | Allow modifying notebook titles |\n| `tools.delete_notebook` | `true` | Allow deleting notebooks |\n| `tools.create_tag` | `true` | Allow creating new tags |\n| `tools.update_tag` | `false` | Allow modifying tag titles |\n| `tools.delete_tag` | `true` | Allow deleting tags |\n| `tools.tag_note` | `true` | Allow adding tags to notes |\n| `tools.untag_note` | `true` | Allow removing tags from notes |\n| `tools.find_notes` | `true` | Allow text search across notes (with task filtering) |\n| `tools.find_notes_with_tag` | `true` | Allow finding notes by tag (with task filtering) |\n| `tools.find_notes_in_notebook` | `true` | Allow finding notes by notebook (with task filtering) |\n| `tools.get_all_notes` | `false` | Allow getting all notes (disabled by default - can fill context window) |\n| `tools.get_note` | `true` | Allow getting specific notes |\n| `tools.list_notebooks` | `true` | Allow listing all notebooks |\n| `tools.list_tags` | `true` | Allow listing all tags |\n| `tools.get_tags_by_note` | `true` | Allow getting tags for specific notes |\n| `tools.ping_joplin` | `true` | Allow testing server connectivity |\n\n#### Content Exposure (Privacy Settings)\n| Option | Default | Description |\n|--------|---------|-------------|\n| `content_exposure.search_results` | `\"preview\"` | Content visibility in search results: `\"none\"`, `\"preview\"`, `\"full\"` |\n| `content_exposure.individual_notes` | `\"full\"` | Content visibility for individual notes: `\"none\"`, `\"preview\"`, `\"full\"` |\n| `content_exposure.listings` | `\"none\"` | Content visibility in note listings: `\"none\"`, `\"preview\"`, `\"full\"` |\n| `content_exposure.max_preview_length` | `300` | Maximum length of content previews (characters) |\n\n## Project Structure\n\n- **`run_fastmcp_server.py`** - FastMCP server launcher\n- **`src/joplin_mcp/`** - Main package directory\n  - `fastmcp_server.py` - Server implementation with 21 tools and Pydantic validation types\n  - `config.py` - Configuration management\n  - `server.py` - Legacy server implementation  \n  - `ui_integration.py` - UI integration utilities\n- **`docs/`** - Documentation (troubleshooting, privacy controls, enhancement proposals)\n- **`tests/`** - Test suite\n\n## Testing\n\nTest your connection:\n\n```bash\n# For pip install\njoplin-mcp-server\n\n# For development  \npython run_fastmcp_server.py\n```\n\nYou should see:\n```\nStarting Joplin FastMCP Server...\nSuccessfully connected to Joplin!\nFound X notebooks, Y notes, Z tags\nFastMCP server starting...\nAvailable tools: 21 tools ready\n```\n\n## Complete Tool Reference\n\n| Tool | Permission | Description |\n|------|------------|-------------|\n| **Finding Notes** | | |\n| `find_notes` | Read | Full-text search across all notes (supports task filtering) |\n| `find_notes_with_tag` | Read | Find notes with specific tag (supports task filtering) |\n| `find_notes_in_notebook` | Read | Find notes in specific notebook (supports task filtering) |\n| `get_all_notes` | Read | Get all notes, most recent first *(disabled by default)* |\n| `get_note` | Read | Get specific note by ID |\n| `get_links` | Read | Extract links to other notes from a note |\n| **Managing Notes** | | |\n| `create_note` | Write | Create new notes |\n| `update_note` | Update | Modify existing notes |\n| `delete_note` | Delete | Remove notes |\n| **Managing Notebooks** | | |\n| `list_notebooks` | Read | Browse all notebooks |\n| `create_notebook` | Write | Create new notebooks |\n| `update_notebook` | Update | Modify notebook titles |\n| `delete_notebook` | Delete | Remove notebooks |\n| **Managing Tags** | | |\n| `list_tags` | Read | View all available tags |\n| `create_tag` | Write | Create new tags |\n| `update_tag` | Update | Modify tag titles |\n| `delete_tag` | Delete | Remove tags |\n| `get_tags_by_note` | Read | List tags on specific note |\n| **Tag-Note Relationships** | | |\n| `tag_note` | Update | Add tags to notes |\n| `untag_note` | Update | Remove tags from notes |\n| **System Tools** | | |\n| `ping_joplin` | Read | Test connectivity |\n",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright (c) 2025 Alon Diament\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy\n        of this software and associated documentation files (the \"Software\"), to deal\n        in the Software without restriction, including without limitation the rights\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n        copies of the Software, and to permit persons to whom the Software is\n        furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all\n        copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n        SOFTWARE. ",
    "summary": "Model Context Protocol (MCP) server for Joplin note-taking application",
    "version": "0.3.1",
    "project_urls": {
        "Documentation": "https://github.com/alondmnt/joplin-mcp/blob/main/README.md",
        "Homepage": "https://github.com/alondmnt/joplin-mcp",
        "Issues": "https://github.com/alondmnt/joplin-mcp/issues",
        "Repository": "https://github.com/alondmnt/joplin-mcp"
    },
    "split_keywords": [
        "joplin",
        " mcp",
        " model-context-protocol",
        " notes",
        " ai",
        " assistant"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3cbcb55650b2e7a61b37874c8f91d766d49f27c8e47f7eac24503e8d678747f7",
                "md5": "b4eee08cacede386ec511b03e2109a8d",
                "sha256": "12a46875dcf578d81dd11546ec5bb3908bd89dc21fbf91db57c4259dff7965fb"
            },
            "downloads": -1,
            "filename": "joplin_mcp-0.3.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "b4eee08cacede386ec511b03e2109a8d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 51203,
            "upload_time": "2025-08-01T02:18:42",
            "upload_time_iso_8601": "2025-08-01T02:18:42.542175Z",
            "url": "https://files.pythonhosted.org/packages/3c/bc/b55650b2e7a61b37874c8f91d766d49f27c8e47f7eac24503e8d678747f7/joplin_mcp-0.3.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "f10ac3cd1172c658ef8bf5cbd6ae3693c1d3bdeaf183bcd73363589edd8424ab",
                "md5": "19feee03b7574a88b904680379ba448e",
                "sha256": "656d4c96de7bc5cc97d1a3a710d1fe9806c805339d0717613cc9453cb9a1634d"
            },
            "downloads": -1,
            "filename": "joplin_mcp-0.3.1.tar.gz",
            "has_sig": false,
            "md5_digest": "19feee03b7574a88b904680379ba448e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 63125,
            "upload_time": "2025-08-01T02:18:45",
            "upload_time_iso_8601": "2025-08-01T02:18:45.951211Z",
            "url": "https://files.pythonhosted.org/packages/f1/0a/c3cd1172c658ef8bf5cbd6ae3693c1d3bdeaf183bcd73363589edd8424ab/joplin_mcp-0.3.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-01 02:18:45",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "alondmnt",
    "github_project": "joplin-mcp",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "mcp",
            "specs": [
                [
                    ">=",
                    "1.0.0"
                ]
            ]
        },
        {
            "name": "joppy",
            "specs": [
                [
                    ">=",
                    "1.0.0"
                ]
            ]
        },
        {
            "name": "fastmcp",
            "specs": [
                [
                    ">=",
                    "2.0.0"
                ]
            ]
        },
        {
            "name": "pydantic",
            "specs": [
                [
                    ">=",
                    "2.0.0"
                ]
            ]
        },
        {
            "name": "httpx",
            "specs": [
                [
                    ">=",
                    "0.24.0"
                ]
            ]
        },
        {
            "name": "typing-extensions",
            "specs": [
                [
                    ">=",
                    "4.0.0"
                ]
            ]
        },
        {
            "name": "PyYAML",
            "specs": [
                [
                    ">=",
                    "6.0.0"
                ]
            ]
        },
        {
            "name": "pytest",
            "specs": [
                [
                    ">=",
                    "7.0.0"
                ]
            ]
        },
        {
            "name": "pytest-asyncio",
            "specs": [
                [
                    ">=",
                    "0.21.0"
                ]
            ]
        },
        {
            "name": "pytest-mock",
            "specs": [
                [
                    ">=",
                    "3.10.0"
                ]
            ]
        },
        {
            "name": "coverage",
            "specs": [
                [
                    ">=",
                    "7.0.0"
                ]
            ]
        },
        {
            "name": "black",
            "specs": [
                [
                    ">=",
                    "23.0.0"
                ]
            ]
        },
        {
            "name": "ruff",
            "specs": [
                [
                    ">=",
                    "0.1.0"
                ]
            ]
        },
        {
            "name": "mypy",
            "specs": [
                [
                    ">=",
                    "1.0.0"
                ]
            ]
        },
        {
            "name": "pre-commit",
            "specs": [
                [
                    ">=",
                    "3.0.0"
                ]
            ]
        }
    ],
    "lcname": "joplin-mcp"
}