MCP Aladin Books Server

🚀 Aladdin Book Search MCP Server (Node.js)

This is an MCP (Model Context Protocol) server that utilizes the Aladdin Book Search API. It enables users to search for books, retrieve detailed book information, and access various book lists through the Aladdin platform.

✨ Features

• Book Search: Search for books by title, author, publisher, or keyword.
• Detailed Information: Query detailed book information using ISBN.
• Best Sellers: View the list of Aladdin best sellers (supports category - specific searches).
• Category Search: Search for and view book categories (higher - level categories are displayed first).

📦 Obtain an Aladdin API Key

To use this MCP server, you need an Aladdin API key.

1. Visit the Aladdin TTB website.
2. Sign up and log in.
3. Apply for API key issuance.

📦 Install DXT

DXT file

1. In the cloud desktop, select [Settings] - [Extensions].
2. Drag and drop the downloaded DXT file.
3. Enter the API key.

📦 Configuration

1. Install Dependencies and Build

npm install
npm run build

2. Enter Information in the MCP Client

{
  "mcpServers": {
    "aladin-books": {
      "command": "node",
      "args": [
        "<Path>/mcp-aladin-books-server/dist/index.js"
      ],
      "env": {
        "ALADIN_TTB_KEY": "Your_Aladdin_TTB_Key"
      }
    }
  }
}

🛠️ Tools

1. search_books

Search for books.

Parameters:

• query (string): Search term.
• searchType (enum): Search type (Title, Author, Publisher, Keyword).
• maxResults (number): Maximum number of results (1 - 100, default: 10).
• start (number): Search start number (default: 1).

2. get_book_detail

Query detailed book information using ISBN.

Parameters:

• isbn (string): The ISBN of the book (10 - digit or 13 - digit).

3. get_bestsellers

Query the list of best - selling books. Category - specific searches are available.

Parameters:

• maxResults (number): Maximum number of results (1 - 100, default: 10).
• start (number): Search start number (default: 1).
• categoryId (string, optional): Category ID (CID) - Restrict the search to a specific category.

4. get_new_books

Query the list of all new books. Category - specific searches are available.

Parameters:

• maxResults (number): Maximum number of results (1 - 100, default: 10).
• start (number): Search start number (default: 1).
• categoryId (string, optional): Category ID (CID) - Restrict the search to a specific category.

5. get_special_new_books

Query the list of notable new books. Category - specific searches are available.

Parameters:

• maxResults (number): Maximum number of results (1 - 100, default: 10).
• start (number): Search start number (default: 1).
• categoryId (string, optional): Category ID (CID) - Restrict the search to a specific category.

6. get_editor_choice

Query the list of editor - recommended books. Category - specific searches are available.

Parameters:

• maxResults (number): Maximum number of results (1 - 100, default: 10).
• start (number): Search start number (default: 1).
• categoryId (string, optional): Category ID (CID) - Restrict the search to a specific category.

7. get_blogger_best

Query the list of blogger best - selling books. Only domestic books can be queried, and category - specific searches are available.

Parameters:

• maxResults (number): Maximum number of results (1 - 100, default: 10).
• start (number): Search start number (default: 1).
• categoryId (string, optional): Category ID (CID) - Restrict the search to a specific category.

8. search_categories

Search for book categories. Higher - level categories are displayed first.

Parameters:

• searchTerm (string): The name of the category to search for.
• maxResults (number): Maximum number of results (1 - 50, default: 20).

9. get_popular_categories

Query the list of frequently used major categories. Higher - level categories are displayed first.

Parameters:

• limit (number): The number of categories to display (1 - 50, default: 20).

10. format_books_table

Organize and display book information in a table format. It supports searches, ISBN queries, and various book list queries.

Parameters:

• type (enum): Query type (search, isbn, bestseller, new_books, special_new_books, editor_choice, blogger_best).
• query (string, optional): Search term (required when type is search).
• isbn (string, optional): ISBN (required when type is isbn).
• searchType (enum): Search type (Title, Author, Publisher, Keyword, default: Title).
• maxResults (number): Maximum number of results (1 - 50, default: 10).
• categoryId (string, optional): Category ID (restrict the category when querying lists).

💻 Usage Examples

You can use it in the MCP client as follows:

// Book search
await callTool('search_books', {
  query: 'Python',
  searchType: 'Title',
  maxResults: 5
});

// Book detailed information
await callTool('get_book_detail', {
  isbn: '9788966262755'
});

// Query all best - selling books
await callTool('get_bestsellers', {
  maxResults: 10
});

// Query category - specific best - selling books
await callTool('get_bestsellers', {
  maxResults: 10,
  categoryId: '798' // Example: Computer category
});

// Query the list of all new books
await callTool('get_new_books', {
  maxResults: 10
});

// Query category - specific new books
await callTool('get_new_books', {
  maxResults: 10,
  categoryId: '798' // Example: Computer category
});

// Query the list of notable new books
await callTool('get_special_new_books', {
  maxResults: 10
});

// Query the list of editor - recommended books
await callTool('get_editor_choice', {
  maxResults: 10
});

// Query the list of blogger best - selling books (domestic books only)
await callTool('get_blogger_best', {
  maxResults: 10,
  categoryId: '798' // Example: Computer category
});

// Search for categories (higher - level first)
await callTool('search_categories', {
  searchTerm: 'Novel',
  maxResults: 10
});

// Query popular categories (higher - level first)
await callTool('get_popular_categories', {
  limit: 10
});

// Display book information in table format (search)
await callTool('format_books_table', {
  type: 'search',
  query: 'Python',
  searchType: 'Title',
  maxResults: 5
});

// Display book information in table format (bestsellers)
await callTool('format_books_table', {
  type: 'bestseller',
  maxResults: 10,
  categoryId: '798'
});

// Display book information in table format (all new books)
await callTool('format_books_table', {
  type: 'new_books',
  maxResults: 10
});

// Display book information in table format (notable new books)
await callTool('format_books_table', {
  type: 'special_new_books',
  maxResults: 10
});

// Display book information in table format (editor - recommended books)
await callTool('format_books_table', {
  type: 'editor_choice',
  maxResults: 10
});

// Display book information in table format (blogger best - selling books)
await callTool('format_books_table', {
  type: 'blogger_best',
  maxResults: 10,
  categoryId: '798'
});

🔧 Development

Project Structure

server/
├── src/
│   ├── index.ts                     # Main server file
│   └── aladin_book_categories.json  # Category information file (large - scale)
├── dist/                            # Build output
├── package.json                     # Package configuration
├── tsconfig.json                    # TypeScript configuration
├── env.example                      # Environment variable example
├── test.js                          # Test file
└── README.md                        # Documentation

Technology Stack

• Node.js: Runtime environment
• TypeScript: Type safety (targeting ES2020, ESNext modules)
• @modelcontextprotocol/sdk: MCP protocol implementation
• axios: HTTP client
• zod: Schema validation

Development Dependencies

• tsx: TypeScript development executor
• @types/node: Node.js type definitions

Build Configuration

• Target: ES2020
• Module: ESNext
• Output Directory: dist/
• Source Map: Included
• Declaration File: Generated
• JSON Module: Supported

🔧 Environment Variables

# Aladdin TTB key (Required)
ALADIN_TTB_KEY=your_aladin_ttb_key_here

📄 License

ISC