grokipedia-MCP by rmahankali - MCP Server

Grokipedia MCP Server - Complete Documentation

Quick Start
Installation
Configuration
Usage Guide
API Reference
Security
Troubleshooting
Legal & Compliance

Quick Start

This is an exploration in Dev phase so please ensure to abide with https://x.ai/legal/terms-of-service

Prerequisites

Python 3.10+
xAI API key (get from https://console.x.ai)
Git
Docker (optional)

5-Minute Setup

# 1. Clone repository
git clone https://github.com/yourusername/grokipedia-mcp.git
cd grokipedia-mcp

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt
pip install -e .

# 4. Configure API key
cp .env.example .env
# Edit .env and add your XAI_API_KEY

# 5. Validate configuration
python -m grokipedia_mcp --validate-config

# 6. Start server
python -m grokipedia_mcp --transport stdio

Installation

Option 1: Development Setup (Recommended for Cursor)

Step 1: Clone & Setup

git clone https://github.com/yourusername/grokipedia-mcp.git
cd grokipedia-mcp

# Create and activate virtual environment
python3 -m venv venv

# On Linux/macOS:
source venv/bin/activate

# On Windows PowerShell:
.\venv\Scripts\Activate.ps1

# On Windows CMD:
venv\Scripts\activate.bat

Step 2: Install Package

# Install in development mode (allows code changes without reinstall)
pip install -e .

# Or with development tools
pip install -e ".[dev]"

Step 3: Create Configuration

cp .env.example .env

# Edit .env with your favorite editor
nano .env  # Linux/macOS
# OR
code .env  # VS Code
# OR
notepad .env  # Windows

Step 4: Verify Installation

python -m grokipedia_mcp --validate-config

Expected output:

✓ Configuration validation successful

Option 2: Docker Setup

# Build image
docker build -t grokipedia-mcp:0.1.0-beta .

# Run container
docker run --rm \\
  -e XAI_API_KEY=your_key \\
  -e GROKIPEDIA_BASE_URL=https://grokipedia.com \\
  grokipedia-mcp:0.1.0-beta

Option 3: Docker Compose

# Create .env file with your credentials
cp .env.example .env
# Edit .env with your API key

# Start services
docker-compose up -d

# View logs
docker-compose logs -f grokipedia-mcp

# Stop services
docker-compose down

Configuration

Environment Variables

Required:

XAI_API_KEY - Your xAI API key (get from https://console.x.ai)

Optional (with sensible defaults):

GROKIPEDIA_BASE_URL=https://grokipedia.com
GROK_MODEL=grok-2-latest
REQUEST_TIMEOUT=30
MAX_RETRIES=3
CACHE_ENABLED=true
CACHE_TTL=3600
ENABLE_GROK_ENHANCEMENT=true
LOG_LEVEL=INFO

Getting Your xAI API Key

Visit Console:
- Go to https://console.x.ai
- Sign in with your xAI account (or create one)
Create API Key:
- Navigate to "API Keys" section
- Click "Create New Key"
- Copy the key immediately (shown only once)
Add to .env:
```
XAI_API_KEY=xai_xxxxxxxxxxxxxxxxxxxxx
```

Test Configuration:

python -m grokipedia_mcp --validate-config

Configuration Validation

The system validates all settings on startup:

# Run validation without starting server
python -m grokipedia_mcp --validate-config

Validation checks:

✓ XAI_API_KEY is set and properly formatted
✓ API key length is valid (20+ characters)
✓ GROKIPEDIA_BASE_URL starts with http:// or https://
✓ REQUEST_TIMEOUT is between 1-300 seconds
✓ MAX_RETRIES is between 0-10
✓ CACHE_TTL is non-negative

Usage Guide

Using with Cursor IDE

Setup MCP Integration

Create configuration file:
- Create .cursor/mcp.json in your project root (on Windows, use forward slashes):

{
  "mcpServers": {
    "grokipedia": {
      "command": "C:\\absolute\\path\\to\\grokipedia-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "grokipedia_mcp"],
      "env": {
        "XAI_API_KEY": "your_xai_api_key_here",
        "GROKIPEDIA_BASE_URL": "https://grokipedia.com",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Important: Replace the Python path with your actual path:

Windows: C:\\Users\\YourName\\grokipedia-mcp\\venv\\Scripts\\python.exe
Mac: /Users/YourName/grokipedia-mcp/venv/bin/python
Linux: /home/username/grokipedia-mcp/venv/bin/python

Restart Cursor to load the MCP configuration
Verify MCP is active:
- Settings → Features → MCP
- Should see "grokipedia" in the list

Using in Cursor Chat

In Cursor chat, you can now use Grokipedia:

User: Search Grokipedia for "Artificial Intelligence"

Cursor will use the search tool automatically

Available commands:

"Search Grokipedia for [topic]"
"Get the Grokipedia article about [topic]"
"Summarize Grokipedia article on [topic]"
"Check cache statistics"
"Clear Grokipedia cache"

Using as Standalone MCP Server

Stdio Transport (Local)

python -m grokipedia_mcp --transport stdio

Connect from any MCP client that supports stdio.

SSE Transport (Remote)

python -m grokipedia_mcp --transport sse --host 0.0.0.0 --port 8080

Connect from remote clients at http://your-ip:8080

Using Programmatically

import asyncio
from grokipedia_mcp.grokipedia_client import GrokipediaClient
from grokipedia_mcp.config import Config

async def main():
    # Initialize client
    config = Config()
    client = GrokipediaClient(config)
    
    # Search
    results = await client.search("artificial intelligence", limit=5)
    print(results)
    
    # Get article
    article = await client.get_article("Machine Learning", use_grok=True)
    print(article["content"])
    
    # Get summary
    summary = await client.get_summary("Neural Networks")
    print(summary["summary"])
    
    # Cleanup
    await client.close()

asyncio.run(main())

API Reference

Available Tools

1. search_grokipedia

Search for articles on Grokipedia.

Parameters:

query (string, required): Search query (max 500 characters)
limit (integer, optional): Max results to return (1-50, default: 10)

Returns:

{
  "query": "artificial intelligence",
  "limit": 10,
  "results": [
    {
      "title": "Artificial Intelligence",
      "snippet": "Artificial intelligence (AI) is...",
      "url": "https://grokipedia.com/wiki/Artificial_Intelligence"
    }
  ],
  "count": 1,
  "status": "success"
}

Example:

User: "Search Grokipedia for machine learning with limit 5"

2. get_grokipedia_article

Retrieve full article content from Grokipedia.

Parameters:

title (string, required): Article title (max 200 characters)
use_grok_enhancement (boolean, optional): Enhance with Grok AI (default: true)

Returns:

{
  "title": "Machine Learning",
  "content": "# Machine Learning\n\nMachine Learning (ML)...",
  "url": "https://grokipedia.com/wiki/Machine_Learning",
  "source": "grokipedia",
  "grok_enhanced": true,
  "status": "success"
}

Example:

User: "Get the full Grokipedia article about quantum computing"

3. get_grokipedia_summary

Get a concise summary of an article.

Parameters:

title (string, required): Article title

Returns:

{
  "title": "Deep Learning",
  "summary": "Deep Learning is a subset of machine learning...",
  "url": "https://grokipedia.com/wiki/Deep_Learning",
  "status": "success"
}

4. get_cache_stats

Get current cache statistics.

Returns:

{
  "memory_cache_items": 5,
  "file_cache_items": 12,
  "cache_dir": "/app/.cache",
  "ttl_seconds": 3600
}

5. clear_cache

Clear all cached data.

Returns:

"✓ Cache cleared successfully"

6. validate_configuration

Validate server configuration.

Returns:

✓ Configuration valid

- grokipedia_base_url: https://grokipedia.com
- grok_model: grok-2-latest
- request_timeout: 30
- max_retries: 3
- cache_enabled: true
- cache_ttl: 3600
- enable_grok_enhancement: true
- xai_api_key_configured: true

Security

API Key Security

Best Practices:

✓ Never commit .env to Git
✓ Use .env.example as template
✓ Rotate API keys regularly
✓ Use separate keys for development/production
✓ Monitor API key usage in xAI console

Secure Configuration:

# Set permissions on .env file (Unix/Linux/macOS)
chmod 600 .env

# Verify .gitignore includes .env
grep "^.env$" .gitignore

SSL/TLS Security

The client always verifies SSL certificates:

# In grokipedia_client.py
self.session = httpx.AsyncClient(verify=True)  # Always enabled

Input Validation

All user inputs are validated:

# Query validation
if len(query) > 500:
    raise ValueError("Query too long (max 500 characters)")

# Limit validation
if not (1 <= limit <= 50):
    raise ValueError("Limit must be between 1 and 50")

Error Handling

Errors are handled gracefully without exposing sensitive information:

# ✓ Safe error message
return {"error": "Failed to fetch article", "status": "failed"}

# ✗ Unsafe - exposes system details
return {"error": str(e), "traceback": traceback.format_exc()}

Rate Limiting

Implement rate limiting to prevent abuse:

# Environment variable
MAX_RETRIES=3  # Retry failed requests max 3 times
REQUEST_TIMEOUT=30  # Timeout after 30 seconds

Data Privacy

✓ No data is stored permanently
✓ Cache files use MD5 hashes (not reversible)
✓ Logs don't include sensitive API keys
✓ HTTPS encryption for all API calls

Troubleshooting

Issue: "XAI_API_KEY not set"

Solution:

# 1. Verify .env file exists
ls -la .env

# 2. Check contents
cat .env | grep XAI_API_KEY

# 3. Re-validate configuration
python -m grokipedia_mcp --validate-config

Issue: "Command not found: grokipedia-mcp"

Solution:

# 1. Ensure package is installed in editable mode
pip install -e .

# 2. Try full path
python -m grokipedia_mcp --validate-config

# 3. Verify venv is activated
which python  # Should show venv path

Issue: "Connection refused" or "Network error"

Solution:

# 1. Check Grokipedia is accessible
curl https://grokipedia.com

# 2. Verify API key works
curl -H "Authorization: Bearer YOUR_KEY" https://api.x.ai/v1/models

# 3. Check firewall/proxy settings

Issue: "Module not found" errors

Solution:

# Reinstall dependencies
pip install -r requirements.txt

# Or full reinstall
pip uninstall grokipedia-mcp
pip install -e .

Issue: Cursor MCP not connecting

Solution:

Verify .cursor/mcp.json exists with correct Python path
Restart Cursor completely
Check Cursor logs: Settings → MCP → View Logs

Test server directly:

python -m grokipedia_mcp --validate-config

Issue: Cache not working

Solution:

# Check cache status
python -c "from grokipedia_mcp.server import get_client; import asyncio; print(asyncio.run(get_client().cache.get_stats()))"

# Clear cache
python -m grokipedia_mcp --cache-clear

Legal & Compliance

Terms of Service Agreement

By using this Grokipedia MCP Server, you agree to:

1. xAI API Terms:

You are responsible for compliance with xAI's Terms of Service
You must use your own xAI API key
You cannot bypass API authentication
You cannot resell API access

2. Grokipedia Terms:

Respect Grokipedia's license terms (see LEGAL.md)
Provide appropriate attribution
Follow their usage policies

3. Data Usage:

Data accessed is subject to Grokipedia's data policies
You are responsible for data privacy compliance
Content is provided "as is"

License

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

Third-Party Licenses

See THIRD-PARTY-LICENSES file for complete list.

Support

For issues:

GitHub Issues: https://github.com/yourusername/grokipedia-mcp/issues
xAI Support: support@x.ai
Grokipedia: https://github.com/AppleLamps/Grokipedia

Version: 0.1.0-beta
Last Updated: November 2025
Status: Beta Release - Use at your own risk

rmahankali/grokipedia-MCP

Grokipedia MCP Server - Complete Documentation

Table of Contents

Quick Start

Prerequisites

5-Minute Setup

Installation

Option 1: Development Setup (Recommended for Cursor)

Step 1: Clone & Setup

Step 2: Install Package

Step 3: Create Configuration

Step 4: Verify Installation

Option 2: Docker Setup

Option 3: Docker Compose

Configuration

Environment Variables

Getting Your xAI API Key

Configuration Validation

Usage Guide

Using with Cursor IDE

Setup MCP Integration

Using in Cursor Chat

Using as Standalone MCP Server

Stdio Transport (Local)

SSE Transport (Remote)

Using Programmatically

API Reference

Available Tools

1. search_grokipedia

2. get_grokipedia_article

3. get_grokipedia_summary

4. get_cache_stats

5. clear_cache

6. validate_configuration

Security

API Key Security

SSL/TLS Security

Input Validation

Error Handling

Rate Limiting

Data Privacy

Troubleshooting

Issue: "XAI_API_KEY not set"

Issue: "Command not found: grokipedia-mcp"

Issue: "Connection refused" or "Network error"

Issue: "Module not found" errors

Issue: Cursor MCP not connecting

Issue: Cache not working

Legal & Compliance

Terms of Service Agreement

License

Third-Party Licenses

Support