Things MCP Server

Instructions

Implementation Reference

• things_server.py:187-199 (handler)

  The main handler function for the 'search_todos' MCP tool. It is decorated with @mcp.tool, which registers it with the FastMCP server. The function takes a query string, searches Things todos using things.search(), formats the results with format_todo(), and returns a formatted string. The type annotations and docstring define the input/output schema.

  @mcp.tool
  async def search_todos(query: str) -> str:
      """Search todos by title or notes
      
      Args:
          query: Search term to look for in todo titles and notes
      """
      todos = things.search(query, include_items=True)
      if not todos:
          return f"No todos found matching '{query}'"
      
      formatted_todos = [format_todo(todo) for todo in todos]
      return "\n\n---\n\n".join(formatted_todos)

• things_server.py:187-187 (registration)

  The @mcp.tool decorator registers the search_todos function as an MCP tool.

  @mcp.tool