favqs/mcp-server

FavQs MCP Server

A Model Context Protocol (MCP) server implementation that provides access to the FavQs API for quote management and search functionality.

Features

• Quote Search: Search quotes by keyword, author, or tag
• Quote Retrieval: Get specific quotes by ID
• Quote of the Day: Retrieve the daily featured quote
• User Authentication: Login with FavQs credentials
• Favorites Management: Add and remove quotes from favorites (requires authentication)

Installation

Prerequisites

• Ruby (any recent version)
• Claude Desktop or another MCP-compatible client
• FavQs API token

Getting Your FavQs API Token

1. Visit FavQs API documentation
2. Sign up for a FavQs account if you don't have one
3. Generate your API token from your account settings

Setup

1. Clone this repository:

   git clone <repository-url>
   cd favqs-mcp-server
   

2. Make the server executable:

   chmod +x favqs_mcp_server.rb
   

3. Set your API token as an environment variable:

   export FAVQS_API_TOKEN="your-api-token-here"
   

Configuration

Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

You can use the provided example as a template:

cp claude_desktop_config.example.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Then edit the config file with your actual values:

• Replace /absolute/path/to/favqs_mcp_server.rb with the actual absolute path to the server file
• Replace your-favqs-api-token with your actual FavQs API token

Example configuration:

{
  "mcpServers": {
    "favqs": {
      "command": "ruby",
      "args": [
        "/absolute/path/to/favqs_mcp_server.rb"
      ],
      "env": {
        "FAVQS_API_TOKEN": "your-favqs-api-token"
      }
    }
  }
}

Other MCP Clients

For other MCP clients, use:

• Command: ruby favqs_mcp_server.rb
• Environment Variable: FAVQS_API_TOKEN=your-api-token-here

Available Tools

search_quotes

Search for quotes with various filters.

Parameters:

• filter (string, optional): Search term or keyword
• type (string, optional): Type of search ("author" or "tag")
• page (integer, optional): Page number (default: 1)

Example: Search for quotes containing "wisdom"

get_quote

Retrieve a specific quote by its ID.

Parameters:

• quote_id (integer, required): The ID of the quote

Example: Get quote with ID 12345

get_quote_of_the_day

Get the current quote of the day.

Parameters: None

authenticate_user

Authenticate with your FavQs account credentials.

Parameters:

• login (string, required): Username or email
• password (string, required): Account password

Note: Authentication is required for favorites management.

favorite_quote

Add a quote to your favorites list.

Parameters:

• quote_id (integer, required): The ID of the quote to favorite

Requirements: Must be authenticated first

unfavorite_quote

Remove a quote from your favorites list.

Parameters:

• quote_id (integer, required): The ID of the quote to unfavorite

Requirements: Must be authenticated first

Usage Examples

1. Search for quotes about love:

   Use the search_quotes tool with filter: "love"
   

2. Get a specific quote:

   Use the get_quote tool with quote_id: 12345
   

3. Authenticate and favorite a quote:

   First use authenticate_user with your credentials
   Then use favorite_quote with the desired quote_id
   

Error Handling

The server provides comprehensive error handling for:

• Missing or invalid API tokens
• Authentication failures
• Network connectivity issues
• Invalid parameters
• API rate limiting

All errors are returned in a structured format with descriptive messages.

Development

Running Locally

export FAVQS_API_TOKEN="your-api-token"
ruby favqs_mcp_server.rb

The server communicates via JSON-RPC over STDIN/STDOUT as per the MCP specification.

Logging

The server logs information and errors to STDERR for debugging purposes.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the file for details.

Support

For issues related to:

• This MCP server: Open an issue in this repository
• FavQs API: Check the FavQs API documentation
• MCP specification: See the Model Context Protocol documentation

Version History

• 1.0.0: Initial release with core quote search and favorites functionality