Joplin MCP Server

Instructions

Implementation Reference

• src/mcp/joplin_mcp.py:99-127 (handler)

  MCP tool handler for 'get_note': async function decorated with @mcp.tool() that retrieves a note using the JoplinAPI and returns formatted dict.
  @mcp.tool() async def get_note(note_id: str) -> Dict[str, Any]: """Get a specific note by ID. Args: note_id: ID of the note to retrieve Returns: Dictionary containing the note data """ if not api: return {"error": "Joplin API client not initialized"} try: note = api.get_note(note_id) return { "status": "success", "note": { "id": note.id, "title": note.title, "body": note.body, "created_time": note.created_time.isoformat() if note.created_time else None, "updated_time": note.updated_time.isoformat() if note.updated_time else None, "is_todo": note.is_todo } } except Exception as e: logger.error(f"Error getting note: {e}") return {"error": str(e)}
• src/joplin/joplin_api.py:275-293 (helper)

  Helper method in JoplinAPI class: fetches note from Joplin REST API and parses into JoplinNote object.
  def get_note(self, note_id: str) -> JoplinNote: """Get a specific note by ID. Args: note_id: ID of the note to retrieve Returns: JoplinNote object Raises: requests.exceptions.RequestException: If note not found or other error """ # Explizit alle wichtigen Felder anfordern, insbesondere den Body params = { "fields": "id,title,body,created_time,updated_time,is_todo" } response = self._make_request("GET", f"notes/{note_id}", params=params) return JoplinNote.from_api_response(response)
• src/joplin/joplin_api.py:34-173 (schema)

  Dataclass schema for JoplinNote used to structure the note data returned by the API.
  class JoplinNote: """Represents a Joplin note with its attributes. Reference: https://joplinapp.org/help/api/references/rest_api/#notes Attributes: id: Unique identifier title: Note title body: Note content in Markdown format created_time: Creation timestamp updated_time: Last update timestamp is_conflict: Whether this note is in conflict latitude: Geographic latitude longitude: Geographic longitude altitude: Geographic altitude author: Note author source_url: Source URL is_todo: Whether this is a todo item todo_due: Todo due date todo_completed: Todo completion date source: Note source source_application: Source application application_data: Application-specific data order: Sort order user_created_time: User creation timestamp user_updated_time: User update timestamp encryption_cipher_text: Encrypted content encryption_applied: Whether encryption is applied markup_language: Markup language used is_shared: Whether note is shared share_id: Share identifier conflict_original_id: Original note ID if in conflict master_key_id: Master key identifier parent_id: Parent folder ID """ id: str title: str body: str | None = None created_time: datetime | None = None updated_time: datetime | None = None is_conflict: bool = False latitude: float | None = None longitude: float | None = None altitude: float | None = None author: str | None = None source_url: str | None = None is_todo: bool = False todo_due: datetime | None = None todo_completed: datetime | None = None source: str | None = None source_application: str | None = None application_data: dict[str, Any] | None = None order: int | None = None user_created_time: datetime | None = None user_updated_time: datetime | None = None encryption_cipher_text: str | None = None encryption_applied: bool = False markup_language: int | None = None is_shared: bool = False share_id: str | None = None conflict_original_id: str | None = None master_key_id: str | None = None parent_id: str | None = None @classmethod def from_api_response(cls, data: dict[str, Any]) -> "JoplinNote": """Create a JoplinNote instance from API response data. Args: data: Raw API response dictionary Returns: JoplinNote instance Raises: ValueError: If required fields are missing """ try: logger.debug(f"Creating JoplinNote from API data: {data}") # Ensure essential fields exist if "id" not in data or "title" not in data: msg = f"Missing essential fields (id/title) in API response: {data}" raise ValueError(msg) # Convert timestamps to datetime objects created_time = ( datetime.fromtimestamp(data["created_time"] / 1000) if data.get("created_time") else None ) updated_time = ( datetime.fromtimestamp(data["updated_time"] / 1000) if data.get("updated_time") else None ) user_created_time = ( datetime.fromtimestamp(data["user_created_time"] / 1000) if data.get("user_created_time") else None ) user_updated_time = ( datetime.fromtimestamp(data["user_updated_time"] / 1000) if data.get("user_updated_time") else None ) todo_due = ( datetime.fromtimestamp(data["todo_due"] / 1000) if data.get("todo_due") else None ) todo_completed = ( datetime.fromtimestamp(data["todo_completed"] / 1000) if data.get("todo_completed") else None ) return cls( id=data["id"], title=data["title"], body=data.get("body"), created_time=created_time, updated_time=updated_time, is_conflict=data.get("is_conflict", False), latitude=data.get("latitude"), longitude=data.get("longitude"), altitude=data.get("altitude"), author=data.get("author"), source_url=data.get("source_url"), is_todo=data.get("is_todo", False), todo_due=todo_due, todo_completed=todo_completed, source=data.get("source") ) except Exception as e: logger.error(f"Error creating JoplinNote: {e}") raise
• src/mcp/joplin_mcp.py:99-99 (registration)

  Decorator that registers the get_note function as an MCP tool.
  @mcp.tool()