Anki MCP Server

Instructions

Implementation Reference

• src/anki_mcp/server.py:12-12 (registration)

  Registration of the 'get-collection-overview' tool, binding the FastMCP app.tool decorator to the handler function get_collection_overview.

  app.tool(name="get-collection-overview", description="Get comprehensive information about the Anki collection including decks, models, and fields")(get_collection_overview)

• src/anki_mcp/tools/get_collection_overview.py:5-105 (handler)

  The handler function implementing the tool logic: asynchronously fetches decks, models, tags, and field information from AnkiConnect API using helper, formats into TextContent blocks, handles errors.

  async def get_collection_overview() -> list[types.TextContent]:
      """
      Get comprehensive information about the Anki collection:
      - Available decks
      - Available note models
      - Fields for each model
      - Tags used
      
      Returns a list of TextContent objects with formatted information.
      """
      results = []
      
      # Get decks
      decks_result = await make_anki_request("deckNames")
      if not decks_result["success"]:
          return [types.TextContent(
              type="text", 
              text=f"\nFailed to retrieve decks: {decks_result['error']}"
          )]
          
      decks = decks_result["result"]
      results.append(
          types.TextContent(
              type="text",
              text=f"\nAvailable decks in Anki ({len(decks)}):\n" + 
                   "\n".join(f"- {deck}" for deck in decks)
          )
      )
      
      # Get models
      models_result = await make_anki_request("modelNames")
      if not models_result["success"]:
          return [types.TextContent(
              type="text",
              text=f"\nFailed to retrieve models: {models_result['error']}"
          )]
          
      models = models_result["result"]
      results.append(
          types.TextContent(
              type="text",
              text=f"\nAvailable note models in Anki ({len(models)}):\n" + 
                   "\n".join(f"- {model}" for model in models)
          )
      )
  
      tags_result = await make_anki_request("getTags")
      if not tags_result["success"]:
          return [types.TextContent(
              type="text",
              text=f"\nFailed to retrieve tags: {tags_result['error']}"
          )]
      if tags := tags_result["result"]:
          results.append(
              types.TextContent(
                  type="text",
                  text=f"\nTags used in Anki ({len(tags)}): {', '.join(tags)}"
              )
          )
      
      # Get fields for each model
      for model_name in models:
          # Get field names
          names_result = await make_anki_request("modelFieldNames", modelName=model_name)
          
          # Get field descriptions
          descriptions_result = await make_anki_request("modelFieldDescriptions", modelName=model_name)
          
          if names_result["success"] and descriptions_result["success"]:
              field_names = names_result["result"]
              field_descriptions = descriptions_result["result"]
              
              # Combine fields and descriptions
              field_info = []
              for name, description in zip(field_names, field_descriptions):
                  desc_text = f": {description}" if description else ""
                  field_info.append(f"  - {name}{desc_text}")
              
              results.append(
                  types.TextContent(
                      type="text",
                      text=f"\nFields for model '{model_name}' ({len(field_names)}):\n" + 
                           "\n".join(field_info)
                  )
              )
          elif not names_result["success"]:
              results.append(
                  types.TextContent(
                      type="text",
                      text=f"\nFailed to retrieve field names for '{model_name}': {names_result['error']}"
                  )
              )
          else:
              results.append(
                  types.TextContent(
                      type="text",
                      text=f"\nFailed to retrieve field descriptions for '{model_name}': {descriptions_result['error']}"
                  )
              )
      
      return results 

• src/anki_mcp/tools/utils.py:10-33 (helper)

  Shared helper utility function for making HTTP requests to AnkiConnect API, used extensively in the get_collection_overview handler and other tools.

  async def make_anki_request(action: str, **params) -> Dict[str, Any]:
      """Make a request to the Anki Connect API with proper error handling."""
      request_data = {
          "action": action,
          "version": ANKI_CONNECT_VERSION
      }
      
      if params:
          request_data["params"] = params
      
      async with httpx.AsyncClient() as client:
          try:
              response = await client.post(ANKI_CONNECT_URL, json=request_data, timeout=30.0)
              response.raise_for_status()
              result = response.json()
              
              # Anki Connect returns an object with either a result or error field
              if "error" in result and result["error"]:
                  return {"success": False, "error": result["error"]}
              
              return {"success": True, "result": result.get("result")}
          except Exception as e:
              return {"success": False, "error": str(e)}