Skip to main content
Glama

MCP Seekr Server

by seekr-sh
GitHub
Python
MIT License
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Seekr Server

A production-ready Model Context Protocol (MCP) server that provides web search and content extraction capabilities via the Seekr API.

📋 Requirements

  • Python 3.10+: This MCP server requires Python 3.10 or higher to run

✨ Features

  • Web Search: Search Google and Wikipedia with advanced filtering

  • Content Extraction: Extract clean text content from any webpage

  • Input Validation: Comprehensive validation for URLs and search queries

  • Rate Limiting: Built-in protection against API abuse (100 calls/minute)

  • Health Monitoring: Health check endpoint for monitoring

  • Environment Configuration: Configurable via environment variables

  • Production Ready: Comprehensive error handling and logging

  • MCP Compatible: Works with all MCP-enabled AI clients

🚀 Quick Start

Installation

# Clone the repository git clone https://github.com/seekr-sh/mcp-server-seekr.git cd mcp-seekr # Install dependencies pip install -r requirements.txt # Optional: Create and configure .env file cp .env.example .env

Running the Server

# Start the server (for development) python seekr.py # Or after installation mcp-server-seekr

The server runs with stdio transport for MCP client compatibility.

🔧 Configuration

Environment Variables

Create a .env file in the project root:

# Seekr API Configuration SEEKR_BASE_URL=https://engine.seekr.sh SEEKR_API_KEY=your_api_key_here SEEKR_TIMEOUT=30 SEEKR_MAX_RETRIES=3 # Rate Limiting MAX_CALLS_PER_MINUTE=100 # Logging LOG_LEVEL=INFO # Server Configuration (optional) PORT=8000 HOST=127.0.0.1

Note: You can also set these as environment variables directly instead of using a .env file. The application will automatically load from .env if it exists, or fall back to system environment variables.

MCP Client Configuration

For Claude Desktop

Add to your Claude Desktop config file:

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

{ "mcpServers": { "seekr": { "command": "uvx", "args": ["mcp-server-seekr"], "env": { "SEEKR_API_KEY": "your-api-key-here" } } } }

Alternative configuration (using Python directly):

{ "mcpServers": { "seekr": { "command": "python3", "args": ["/path/to/mcp-seekr/seekr.py"], "env": { "SEEKR_API_KEY": "your-api-key-here" } } } }

This server uses stdio transport for MCP compatibility.

🛠️ Tools

seekr_query

Search the web using Google.

Parameters:

  • query (string, required): Search query (max 500 characters)

  • num (integer, optional): Number of results 1-50 (default: 10)

Example:

{ "query": "latest AI developments 2024", "num": 5 }

seekr_prism

Extract text content from a webpage URL.

Parameters:

  • url (string, required): Valid HTTP/HTTPS URL to extract content from

Example:

{ "url": "https://example.com/article" }

"status": "healthy", "timestamp": 1694598000.123, "version": "1.0.0", "services": { "seekr_api": "healthy" } }

- **Robust Error Handling**: Automatic retries and detailed error reporting - **Type Safety**: Full TypedDict definitions for reliable API interactions ## 📋 Installation ### Prerequisites - Python 3.10 or higher - pip package manager ### Using pip ```bash # Install from source git clone <your-repo-url> cd mcp-server-seekr pip install -e .

Development Installation

# Clone the repository git clone <your-repo-url> cd mcp-server-seekr # Install with development dependencies pip install -e ".[dev]"

⚙️ Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

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

{ "mcpServers": { "seekr": { "command": "seekr-mcp", "env": { "SEEKR_API_KEY": "your-api-key-here" } } } }

Environment Variables (Optional)

Create a .env file in your project root:

# Seekr API Configuration (if needed in future) SEEKR_BASE_URL=https://seekr.dfs.im SEEKR_TIMEOUT=30 SEEKR_MAX_RETRIES=3

🎯 Usage Examples

When to Use the Tools

Use

  • Current information, recent news, or developments that may have changed since your last training data

  • Real-time web search results from Google or Wikipedia

  • Localized content in different languages and regions

  • Advanced search operators (site-specific, file types, date ranges, etc.)

Use

  • To read the actual content of a webpage or article

  • Clean text extraction from websites you can't access directly

  • Analyzing web page content or online documents

Basic Web Search

# Current news and recent developments { "name": "seekr_search", "arguments": { "query": "latest developments in quantum computing 2024", "engine": "google", "language": "en", "num": 10, "time_range": "month" } } # Localized search in Portuguese { "name": "seekr_search", "arguments": { "query": "notícias sobre inteligência artificial no Brasil", "engine": "google", "language": "pt", "region": "BR", "num": 5 } }

Advanced Search with Operators

# Search specific sites for technical documentation { "name": "seekr_search", "arguments": { "query": "machine learning tutorial", "site": "github.com", "filetype": "pdf", "intitle": "guide", "num": 20 } } # News search with time filter { "name": "seekr_search", "arguments": { "query": "climate change solutions", "search_type": "news", "time_range": "week", "language": "en" } }

Web Content Extraction

# Extract article content { "name": "seekr_fetch", "arguments": { "url": "https://example.com/article", "language": "en" } } # Extract Portuguese content { "name": "seekr_fetch", "arguments": { "url": "https://example.com/artigo", "language": "pt" } }
### Web Scraping The `seekr_fetch` tool provides clean content extraction: ```python { "url": "https://example.com/article", "language": "en" }

🔧 API Reference

seekr_search Tool

Performs web searches using Seekr API with support for Google and Wikipedia.

Parameters:

Parameter

Type

Required

Description

query

string

Yes

Search query string

engine

string

No

Search engine: "google" (default) or "wikipedia"

language

string

No

Language code (ISO 639-1, e.g., "en", "es")

region

string

No

Region code (ISO 3166-1 alpha-2, e.g., "US", "GB")

safe_search

integer

No

Safe search level: 0=off, 1=medium, 2=high

time_range

string

No

Time filter: "day", "week", "month", "year"

page

integer

No

Page number (1-based, default: 1)

search_type

string

No

Search type: "web", "images", "videos", "news"

num

integer

No

Number of results (max 100 for Google, 50 for Wikipedia)

Advanced Search Operators:

Parameter

Type

Description

site

string

Limit results to specific domain

filetype

string

Limit to specific file types

inurl

string

Search for pages with word in URL

intitle

string

Search for pages with word in title

exact

string

Exact phrase match

exclude

string

Terms to exclude (comma-separated)

or_terms

string

Alternative terms (comma-separated)

seekr_fetch Tool

Scrapes and extracts clean text content from web pages.

Parameters:

Parameter

Type

Required

Description

url

string

Yes

URL of the webpage to scrape

language

string

No

Language code for content extraction

🏗️ Architecture

mcp-server-seekr/ ├── src/mcp_server_seekr/ │ ├── __init__.py │ ├── main.py # MCP server implementation │ ├── services/ │ │ ├── __init__.py │ │ └── seekr_client.py # Seekr API client │ ├── tools/ │ │ ├── __init__.py │ │ └── search_tool.py # Search tools implementation │ └── types/ │ ├── __init__.py │ └── seekr.py # Type definitions ├── pyproject.toml # Project configuration ├── requirements.txt # Dependencies └── README.md # This file

Components

  • SeekrClient: HTTP client for Seekr API with retry logic and error handling

  • SeekrSearchTools: Business logic layer that handles search and fetch operations

  • Main Server: MCP server implementation with tool registration and request handling

  • Type Definitions: Comprehensive TypedDict definitions for type safety

🚨 Error Handling

The server implements comprehensive error handling:

  • Validation Errors: Missing required parameters

  • API Errors: Seekr API failures with detailed error messages

  • Network Errors: Connection issues with automatic retries

  • Timeout Handling: Configurable request timeouts

🧪 Testing

Run the test suite:

# Install test dependencies pip install -e ".[dev]" # Run tests pytest # Run with coverage pytest --cov=mcp_server_seekr # Run specific test file pytest tests/test_seekr_client.py

🚀 Development

Setting up Development Environment

# Clone and install in development mode git clone <your-repo-url> cd mcp-server-seekr pip install -e ".[dev]" # Run formatting black src/ ruff check src/ # Run type checking mypy src/

Project Structure Guidelines

  • Use TypedDict for all API request/response types

  • Implement proper error handling with detailed error messages

  • Add logging for debugging and monitoring

  • Follow async/await patterns for all I/O operations

  • Include comprehensive docstrings for all public methods

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests for new functionality

  5. Ensure all tests pass

  6. Submit a pull request

📞 Support

For issues and questions:

  • Open an issue on GitHub

  • Check existing issues for solutions

  • Review the Seekr API documentation

🔗 Related Projects

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables web search through Google and Wikipedia plus content extraction from any webpage via the Seekr API. Provides real-time search results with advanced filtering options and clean text extraction capabilities.

  1. 📋 Requirements
    1. ✨ Features
      1. 🚀 Quick Start
        1. Installation
        2. Running the Server
      2. 🔧 Configuration
        1. Environment Variables
        2. MCP Client Configuration
      3. 🛠️ Tools
        1. seekr_query
        2. seekr_prism
        3. Development Installation
      4. ⚙️ Configuration
        1. For Claude Desktop
        2. Environment Variables (Optional)
      5. 🎯 Usage Examples
        1. When to Use the Tools
        2. Basic Web Search
        3. Advanced Search with Operators
        4. Web Content Extraction
      6. 🔧 API Reference
        1. seekr_search Tool
        2. seekr_fetch Tool
      7. 🏗️ Architecture
        1. Components
      8. 🚨 Error Handling
        1. 🧪 Testing
          1. 🚀 Development
            1. Setting up Development Environment
            2. Project Structure Guidelines
          2. 📄 License
            1. 🤝 Contributing
              1. 📞 Support
                1. 🔗 Related Projects

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/seekr-sh/mcp-server-seekr'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server