anki-mcp

Instructions

Implementation Reference

• src/anki_mcp/note_service.py:11-20 (handler)

  The handler function for the 'note_findNotes' tool. It wraps the AnkiConnect 'findNotes' API call, providing input validation via Pydantic and prefixes to 'note_findNotes' upon registration.

  @note_mcp.tool(
      name="findNotes",
      description="Returns an array of note IDs for a given Anki search query.",
  )
  async def find_notes_tool(
      query: Annotated[
          str, Field(description="Anki search query (e.g., 'deck:current card:1').")
      ],
  ) -> List[int]:
      return await anki_call("findNotes", query=query)

• src/anki_mcp/__init__.py:22-29 (registration)

  Registers the note_mcp server into the main anki_mcp instance with 'note' prefix, transforming 'findNotes' tool to 'note_findNotes'.

  async def setup(run_server: bool = True):
      await anki_mcp.import_server("deck", deck_mcp)
      await anki_mcp.import_server("note", note_mcp)
      await anki_mcp.import_server("card", card_mcp)
      await anki_mcp.import_server("model", model_mcp)
      await anki_mcp.import_server("media", media_mcp)
      if run_server:
          await anki_mcp.run_async()

• src/anki_mcp/common.py:8-23 (helper)

  Helper function that performs the actual HTTP POST request to AnkiConnect API, handling errors and invoked by the note_findNotes handler.

  async def anki_call(action: str, **params: Any) -> Any:
      async with httpx.AsyncClient() as client:
          payload = {"action": action, "version": 6, "params": params}
          result = await client.post(ANKICONNECT_URL, json=payload)
          result.raise_for_status()                                      
          result_json = result.json()
          error = result_json.get("error")
          if error:
              raise Exception(f"AnkiConnect error for action '{action}': {error}")
          response = result_json.get("result")
                                                               
                                                                                                       
                                                                                          
          if "result" in result_json:
              return response
          return result_json