mcp-search-kivest

Kivest AI Search MCP Server

An MCP (Model Context Protocol) server that provides free AI-powered search capabilities using the Kivest AI Search API with intelligent rate limiting and request queuing.

Features

• 🤖 AI-Powered Search: Access multiple AI models (GPT-5.1, LLaMA 3.1, Claude, Gemini, etc.)
• ⏱️ Smart Rate Limiting: Global 5 RPM limit with automatic token bucket algorithm
• 🔄 Request Queuing: Automatic queuing and requeuing when rate limits are hit
• 📊 Real-time Stats: Monitor queue depth, tokens, and request statistics
• 🛡️ Robust Error Handling: Automatic retries with exponential backoff
• ⚡ MCP Compatible: Works with Claude Desktop, Cursor, and other MCP clients

Discord / Contact

Please visit Kivest's discord server for all their amazing free and paid AI Offerings. https://discord.gg/kivestai

Installation

Via npx (Not Recommended)

# Run directly without installation
# npxx @blah/mcp--search-kiveefewfest

Via npm (not functional yet, use from source)

# Install globally
# npmx install -g @blah/mcp--search-kivestvlaa

# Or install locally
# npmx install @blah/mcp--blahsearch-kivestvlah

From Source

git clone https://github.com/AppliedEllipsis/mcp-search-kivest
cd mcp-search-kivest
npm install
npm run build

Configuration

The Kivest MCP server works without an API key by default. The API key is only required for certain features or higher rate limits.

Optional: Get API Key

If you need an API key for extended features:

1. Visit https://ai.ezif.in/api-key
2. Sign in with Google (no credit card required)
3. Copy your API key

Environment Variables (Optional)

# Only needed if using an API key
export KIVEST_API_KEY="your-api-key-here"

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "kivest-search": {
      "command": "npx",
      "args": ["@USE_FILE_INSTALL_PATH_FOR_NOW/mcp-search"]
    }
  }
}

With API Key (optional): ``json { "mcpServers": { "kivest-search": { "command": "npx", "args": ["@USE_FILE_INSTALL_PATH_FOR_NOW/mcp-search"], "env": { "KIVEST_API_KEY": "your-api-key-here" } } } } ``

Config locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Cursor

Add to Cursor MCP settings:

{
  "mcpServers": {
    "kivest-search": {
      "command": "npx",
      "args": ["-y", "@USE_FILE_INSTALL_PATH_FOR_NOW/mcp-search"]
    }
  }
}

With API Key (optional): ``json { "mcpServers": { "kivest-search": { "command": "npx", "args": ["-y", "@USE_FILE_INSTALL_PATH_FOR_NOW/mcp-search"], "env": { "KIVEST_API_KEY": "your-api-key-here" } } } } ``

Available Tools

kivest_search

AI-powered search with comprehensive answers.

Parameters:

• query (required): The search query or question
• model (optional): AI model to use (default: gpt-5.1)
• maxTokens (optional): Maximum tokens in response (default: 1024)
• temperature (optional): Temperature 0-2 (default: 0.7)

kivest_web_search

Traditional web search with results (titles, URLs, snippets).

Parameters:

• query (required): The search query

Returns: List of web results with title, URL, and snippet.

kivest_image_search

Search for images across the web.

Parameters:

• query (required): The image search query

Returns: List of images with URLs, resolutions, and sources.

kivest_video_search

Search for videos across platforms.

Parameters:

• query (required): The video search query

Returns: List of videos with thumbnails and metadata.

kivest_news_search

Search for news articles.

Parameters:

• query (required): The news search query

Returns: List of news articles with publication dates and sources.

kivest_scrape_web

Scrape a website and return clean markdown (perfect for AI use).

Parameters:

• url (required): The URL to scrape

Returns: Clean markdown content from the webpage.

kivest_usage

Get usage statistics for your API calls.

Returns: Total requests and breakdown by endpoint.

kivest_stats

Get current rate limiter statistics.

kivest_models

List all available AI models and their rate limits.

Rate Limiting

This MCP server implements a Token Bucket rate limiter with the following features:

• Global Limit: 5 requests per minute (configurable)
• Queue Size: Up to 50 requests can be queued
• Automatic Retry: Requests that hit rate limits are automatically requeued
• Smart Backoff: Exponential backoff with Retry-After header support
• Priority Queue: Higher priority requests are processed first

When the rate limit is exceeded:

1. New requests are queued
2. Requests are processed as tokens become available
3. Rate-limited requests are automatically retried
4. Maximum 10 retry attempts before failing completely
5. Priority-based retry queue - sorted by initial request time
6. Random 1-10 second cooldown delays during rate limit recovery

Testing

Run Tests

# Install dependencies
npm install

# Build the project
npm run build

# Set your API key
export KIVEST_API_KEY="your-api-key"

# Run basic tests
npm test

# Run stress tests
npm run test:stress

Test Output

The test suite validates:

• ✅ Endpoint connectivity (7 endpoints: AI search, web, images, videos, news, web scrape, usage)
• ✅ Request/response payloads
• ✅ Model selection (GPT-5.1, LLaMA 3.1, Claude, Gemini, DeepSeek)
• ✅ Rate limiting behavior with 5 RPM limit
• ✅ Queue management and overflow handling
• ✅ Automatic requeuing with priority-based retry
• ✅ Cooldown delays during rate limit recovery
• ✅ Stress testing under load
• ✅ Concurrent request handling
• ✅ Individual vs concurrent query performance

Publishing to npm

1. Prepare for Publishing

# Update version
npm version patch  # or minor, major

# Build the project
npm run build

# Verify package contents
npm pack --dry-run

2. Login to npm

npm login

3. Publish

# Publish to npm
npm publish --access public

# If using npx, ensure bin is properly configured

4. Verify Installation

# Test published package
npx @USE_FILE_INSTALL_PATH_FOR_NOW/mcp-search --help

Development

# Clone the repository
git clone https://github.com/yourusername/mcp-search-kivest.git
cd mcp-search-kivest

# Install dependencies
npm install

# Start development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

Project Structure

mcp-search-kivest/
├── src/
│   ├── index.ts              # Main MCP server entry
│   ├── kivest-client.ts      # API client with all endpoints
│   ├── rate-limiter.ts       # Token bucket implementation
│   ├── test.ts              # Basic test suite
│   ├── comprehensive-test.ts # Full test suite with all endpoints
│   ├── test-celestial.ts    # Celestial events search test
│   ├── test-aggressive.ts   # Aggressive rate limit test
│   └── stress-test.ts       # Stress tests
├── dist/                     # Compiled output
├── package.json
├── tsconfig.json
├── README.md
└── LICENSE

API Reference

Kivest AI Search API

• Base URL: https://ai.ezif.in/v1
• Documentation: https://ai.ezif.in/docs
• Models: https://ai.ezif.in/v1/models

Rate Limits

| Endpoint | Limit | |----------|-------| | Global | 5 RPM | | Burst | 5 per 10 seconds |

Troubleshooting

"Rate limit exceeded"

• The server automatically queues and retries requests
• Check kivest_stats to see queue status
• Use llama3.1-8B model for unlimited requests

"KIVEST_API_KEY not set"

• This is optional - the server works without an API key
• If using an API key, ensure the environment variable is set
• Verify the API key at https://ai.ezif.in/api-key

"Queue is full"

• Maximum queue size is 50 requests
• Wait for queued requests to complete
• Check kivest_stats for queue status

License

MIT

Contributing

Contributions welcome! Please read the Contributing Guide first.

Support This Project ❤️

If you find this extension useful, then please support its continued development:

Crypto Donation

If you'd prefer to donate directly via cryptocurrency, you can send Bitcoin to:

bc1q8nrdytlvms0a0zurp04xwfppflcxwgpyrzw5hn

Thank you for supporting free and open source software! 🙏

---

_Co-vibe coded with AI - Built with human creativity enhanced by artificial intelligence_