Things MCP Server

Instructions

Implementation Reference

• things_server.py:299-333 (handler)

  MCP tool handler implementation for 'add_project'. Registers the tool with @mcp.tool decorator, defines input schema via parameters and docstring, constructs Things URL using helper, executes it, and returns confirmation.

  @mcp.tool
  async def add_project(
      title: str,
      notes: str = None,
      when: str = None,
      deadline: str = None,
      tags: List[str] = None,
      area_id: str = None,
      area_title: str = None,
      todos: List[str] = None
  ) -> str:
      """Create a new project in Things
      
      Args:
          title: Title of the project
          notes: Notes for the project
          when: When to schedule the project
          deadline: Deadline for the project
          tags: Tags to apply to the project
          area_id: ID of area to add to
          area_title: Title of area to add to
          todos: Initial todos to create in the project
      """
      url = url_scheme.add_project(
          title=title,
          notes=notes,
          when=when,
          deadline=deadline,
          tags=tags,
          area_id=area_id,
          area_title=area_title,
          todos=todos
      )
      url_scheme.execute_url(url)
      return f"Created new project: {title}"

• url_scheme.py:73-93 (helper)

  Helper function that constructs the Things URL scheme for adding a project by preparing parameters and calling construct_url.

  def add_project(title: str, notes: Optional[str] = None, when: Optional[str] = None,
                  deadline: Optional[str] = None, tags: Optional[list[str]] = None,
                  area_id: Optional[str] = None, area_title: Optional[str] = None,
                  todos: Optional[list[str]] = None) -> str:
      """Construct URL to add a new project."""
      params = {
          'title': title,
          'notes': notes,
          'when': when,
          'deadline': deadline,
          'area-id': area_id,
          'area': area_title,
          # Change todos to be newline separated
          'to-dos': '\n'.join(todos) if todos else None
      }
      
      # Handle tags separately since they need to be comma-separated
      if tags:
          params['tags'] = ','.join(tags)
          
      return construct_url('add-project', {k: v for k, v in params.items() if v is not None})

• url_scheme.py:7-18 (helper)

  Helper function to execute the constructed Things URL using osascript (AppleScript) with fallback to webbrowser.

  def execute_url(url: str) -> None:
      """Execute a Things URL without bringing Things to the foreground."""
      try:
          subprocess.run([
              'osascript', '-e', 
              f'tell application "Things3" to open location "{url}"'
          ], check=True, capture_output=True, text=True)
      except subprocess.CalledProcessError:
          # Fallback to webbrowser if osascript fails
          import webbrowser
          webbrowser.open(url)