# TwitterAPI.io Documentation MCP Server

This is an MCP (Model Context Protocol) server that provides offline access to TwitterAPI.io documentation for Claude and other AI assistants. The server bundles a scraped snapshot of 54 API endpoints, 19 guide pages, and 21 blog posts, enabling instant documentation lookup without network latency. Built as an independent community project, it allows developers to query Twitter API documentation directly within their AI assistant conversations through a comprehensive set of tools and resources.

The server implements production-ready features including hybrid caching (memory + disk persistence), advanced search with fuzzy matching and camelCase support, structured logging with SLO tracking, input validation, and MCP Resources for static guide access. It runs on Node.js 18.18.0+ as a pure ES Module with no build step, communicating via stdio transport and supporting structured content outputs for better LLM parsing.

## Installation and Configuration

### Installing in Claude Desktop

```json
{
  "mcpServers": {
    "twitterapi-docs": {
      "command": "npx",
      "args": ["-y", "twitterapi-io-mcp"]
    }
  }
}
```

Add this configuration to:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Installing in Claude Code

```bash
# Global installation (all projects)
claude mcp add --scope user twitterapi-docs -- npx -y twitterapi-io-mcp

# Project-specific installation
claude mcp add twitterapi-docs -- npx -y twitterapi-io-mcp

# Verify installation
claude mcp list
```

### Direct npm usage

```bash
# Run directly with npx
npx -y twitterapi-io-mcp

# Or install globally
npm install -g twitterapi-io-mcp
twitterapi-io-mcp
```

## MCP Tool: search_twitterapi_docs

Search across all TwitterAPI.io documentation including endpoints, guides, and blog posts with fuzzy matching.

```javascript
// Example tool call from MCP client
const result = await client.callTool({
  name: 'search_twitterapi_docs',
  arguments: {
    query: 'advanced search',
    max_results: 10  // Optional: 1-20, default 10
  }
});

// Response structure
{
  content: [{
    type: 'text',
    text: '## "advanced search" - 5 results...'
  }],
  structuredContent: {
    query: 'advanced search',
    max_results: 10,
    cached: false,
    counts: {
      total: 5,
      endpoints: 3,
      pages: 1,
      blogs: 1
    },
    results: [
      {
        type: 'endpoint',
        name: 'tweet_advanced_search',
        title: 'Advanced Search',
        description: 'Search tweets with advanced filters',
        method: 'GET',
        path: '/twitter/tweet/search',
        url: 'https://docs.twitterapi.io/api-reference/endpoint/tweet_advanced_search',
        score: 45.5
      }
    ]
  }
}
```

```bash
# Example cURL equivalent (not actual HTTP - this is an MCP tool)
# Ask Claude: "Search for webhook endpoints in TwitterAPI docs"
# Claude will call: search_twitterapi_docs with query="webhook"
```

## MCP Tool: get_twitterapi_endpoint

Get complete documentation for a specific API endpoint including parameters, cURL examples, and code snippets.

```javascript
// Example tool call
const endpoint = await client.callTool({
  name: 'get_twitterapi_endpoint',
  arguments: {
    endpoint_name: 'get_user_info'
  }
});

// Response structure
{
  content: [{
    type: 'text',
    text: '# Get User Info\n\n## Endpoint Details\n- **Method:** GET...'
  }],
  structuredContent: {
    endpoint_name: 'get_user_info',
    title: 'Get User Info',
    method: 'GET',
    path: '/twitter/user/info',
    full_url: 'https://api.twitterapi.io/twitter/user/info',
    doc_url: 'https://docs.twitterapi.io/api-reference/endpoint/get_user_info',
    description: 'Get detailed information about a Twitter user',
    parameters: [
      {
        name: 'userName',
        required: true,
        description: 'Twitter username (without @)'
      }
    ],
    curl_example: 'curl --request GET \\\n  --url https://api.twitterapi.io/twitter/user/info?userName=elonmusk \\\n  --header \'x-api-key: YOUR_API_KEY\'',
    code_snippets: [],
    raw_text: 'Full documentation text...',
    cached: false,
    markdown: '# Get User Info...'
  }
}
```

```bash
# Common endpoint names to query
get_user_info
get_user_followers
get_user_following
tweet_advanced_search
get_tweet_by_id
add_webhook_rule
get_webhook_rules
```

## MCP Tool: list_twitterapi_endpoints

List all 54 API endpoints organized by category with optional filtering.

```javascript
// List all endpoints
const allEndpoints = await client.callTool({
  name: 'list_twitterapi_endpoints',
  arguments: {}
});

// Filter by category
const userEndpoints = await client.callTool({
  name: 'list_twitterapi_endpoints',
  arguments: {
    category: 'user'  // user, tweet, webhook, stream, action, dm, list, trend, community, other
  }
});

// Response structure
{
  structuredContent: {
    category: 'user',
    total: 54,
    endpoints: [
      {
        name: 'get_user_info',
        method: 'GET',
        path: '/twitter/user/info',
        description: 'Get user information by username',
        category: 'user'
      },
      {
        name: 'get_user_followers',
        method: 'GET',
        path: '/twitter/user/followers',
        description: 'Get followers of a user',
        category: 'user'
      }
    ],
    markdown: '# TwitterAPI.io Endpoints...'
  }
}
```

```bash
# Available categories
user        # 9 endpoints - user info, followers, followings
tweet       # 7 endpoints - search, replies, quotes, retweets
webhook     # 4 endpoints - filter rules management
stream      # 2 endpoints - real-time monitoring
action      # 16 endpoints - create, like, retweet, follow
dm          # 2 endpoints - direct messages
list        # 2 endpoints - list followers/members
trend       # 1 endpoint - trending topics
community   # 5 endpoints - community management
other       # Miscellaneous endpoints
```

## MCP Tool: get_twitterapi_guide

Retrieve full content of documentation pages by their key name.

```javascript
// Get pricing guide
const pricing = await client.callTool({
  name: 'get_twitterapi_guide',
  arguments: {
    guide_name: 'pricing'
  }
});

// Response structure
{
  structuredContent: {
    guide_name: 'pricing',
    title: 'Pricing - twitterapi.io',
    url: 'https://twitterapi.io/pricing',
    description: 'Credit-based pricing with no monthly subscription',
    headers: [
      { level: 1, text: 'Pricing' },
      { level: 2, text: 'Credit System' }
    ],
    paragraphs: ['1 USD = 100,000 Credits...'],
    list_items: ['Credits never expire', 'Bonus credits valid for 30 days'],
    code_snippets: [],
    raw_text: 'Full page content...',
    markdown: '# Pricing...'
  }
}
```

```bash
# Available guide keys
pricing              # Credit system and costs
qps_limits           # Rate limiting by balance level
tweet_filter_rules   # Advanced search filter syntax
changelog            # API changelog
introduction         # Introduction to TwitterAPI.io
authentication       # API key setup guide
readme               # Project overview
```

## MCP Tool: get_twitterapi_url

Fetch documentation by URL with optional live fetching for missing content.

```javascript
// Fetch from offline snapshot
const page = await client.callTool({
  name: 'get_twitterapi_url',
  arguments: {
    url: 'https://twitterapi.io/pricing',
    fetch_live: false  // Default: use offline snapshot
  }
});

// Fetch live if not in snapshot
const livePage = await client.callTool({
  name: 'get_twitterapi_url',
  arguments: {
    url: 'https://docs.twitterapi.io/introduction',
    fetch_live: true  // Fetch from web if missing
  }
});

// Response structure
{
  structuredContent: {
    url: 'https://twitterapi.io/pricing',
    source: 'snapshot',  // or 'live'
    kind: 'page',  // 'endpoint', 'page', or 'blog'
    name: 'pricing',
    title: 'Pricing - twitterapi.io',
    description: 'Credit-based pricing...',
    markdown: '# Pricing...'
  }
}
```

```bash
# URL formats supported
https://twitterapi.io/pricing
https://docs.twitterapi.io/introduction
/pricing                           # Relative URLs (auto-prefixed)
twitterapi.io/pricing             # Missing protocol (auto-added)
docs.twitterapi.io/authentication  # Missing protocol (auto-added)
```

## MCP Tool: get_twitterapi_pricing

Quick access to pricing information including credit costs and QPS limits.

```javascript
const pricing = await client.callTool({
  name: 'get_twitterapi_pricing',
  arguments: {}
});

// Response structure
{
  structuredContent: {
    credits_per_usd: 100000,
    minimum_charge: '15 credits ($0.00015) per request',
    costs: {
      tweets: '15 credits per tweet',
      profiles: '18 credits per user',
      followers: '15 credits per follower',
      list_calls: '150 credits per call'
    },
    qps_limits: {
      free: '1 request per 5 seconds',
      paid: {
        '1000_credits': '3 QPS',
        '5000_credits': '6 QPS',
        '10000_credits': '10 QPS',
        '50000_credits': '20 QPS'
      }
    },
    notes: [
      'Credits never expire',
      'Bonus credits valid for 30 days',
      'Up to 5% discount on bulk purchases',
      'List endpoints: 150 credits/request',
      '~97% cheaper than official Twitter API'
    ],
    markdown: '# TwitterAPI.io Pricing...'
  }
}
```

## MCP Tool: get_twitterapi_auth

Quick access to authentication setup and code examples.

```javascript
const auth = await client.callTool({
  name: 'get_twitterapi_auth',
  arguments: {}
});

// Response structure
{
  structuredContent: {
    header: 'x-api-key',
    base_url: 'https://api.twitterapi.io',
    dashboard_url: 'https://twitterapi.io/dashboard',
    examples: {
      curl: 'curl -X GET "https://api.twitterapi.io/twitter/user/info?userName=elonmusk" \\\n  -H "x-api-key: YOUR_API_KEY"',
      python: 'import requests\n\nresponse = requests.get(\n    "https://api.twitterapi.io/twitter/user/info",\n    params={"userName": "elonmusk"},\n    headers={"x-api-key": "YOUR_API_KEY"}\n)\nprint(response.json())',
      javascript: 'const response = await fetch(\n  "https://api.twitterapi.io/twitter/user/info?userName=elonmusk",\n  { headers: { "x-api-key": "YOUR_API_KEY" } }\n);\nconst data = await response.json();'
    },
    markdown: '# TwitterAPI.io Authentication...'
  }
}
```

```bash
# Authentication flow
# 1. Sign up at https://twitterapi.io/dashboard
# 2. Get your API key from dashboard
# 3. Add header to all requests: x-api-key: YOUR_API_KEY
# 4. Base URL: https://api.twitterapi.io
```

## MCP Resources

Access static documentation via MCP resource URIs for quick reference.

```javascript
// List all resources
const resources = await client.listResources();

// Read pricing resource
const pricing = await client.readResource({
  uri: 'twitterapi://guides/pricing'
});

// Read metrics resource
const metrics = await client.readResource({
  uri: 'twitterapi://metrics'
});

// Response structure for guide resources
{
  contents: [{
    uri: 'twitterapi://guides/pricing',
    mimeType: 'text/markdown',
    text: '# TwitterAPI.io Pricing\n\n## Credit System...'
  }]
}

// Response structure for monitoring resources
{
  contents: [{
    uri: 'twitterapi://metrics',
    mimeType: 'application/json',
    text: JSON.stringify({
      timestamp: '2025-12-13T00:00:00.000Z',
      uptime: 3600,
      requests: {
        total: 150,
        successful: 148,
        failed: 2,
        totalLatency: 7500,
        averageLatency: 50
      },
      cache: {
        hits: 120,
        misses: 30,
        hitRate: '80.0%'
      },
      sloViolations: {
        target: 5,
        acceptable: 2,
        alert: 0
      }
    }, null, 2)
  }]
}
```

```bash
# Documentation Resources
twitterapi://docs/all                  # Full documentation JSON
twitterapi://docs/endpoints            # Endpoint list
twitterapi://endpoints/list            # Endpoint list (alias)
twitterapi://docs/guides               # All guide pages

# Static Guide Resources
twitterapi://guides/pricing            # Pricing guide
twitterapi://guides/authentication     # Auth guide
twitterapi://guides/qps_limits         # Rate limits
twitterapi://guides/qps-limits         # Rate limits (alias)
twitterapi://guides/tweet_filter_rules # Filter syntax
twitterapi://guides/filter-rules       # Filter syntax (alias)
twitterapi://guides/changelog          # API changelog
twitterapi://guides/introduction       # Introduction
twitterapi://guides/readme             # README

# Monitoring Resources
twitterapi://metrics                   # Performance metrics
twitterapi://health                    # Health check
twitterapi://status/freshness          # Data freshness
```

## Advanced Search with Tokenization

The server implements advanced tokenization supporting camelCase, PascalCase, and compound words.

```javascript
// Search tokenization examples
// Input: "getUserInfo" → Tokens: ["get", "user", "info"]
// Input: "get_user_info" → Tokens: ["get", "user", "info"]
// Input: "OAuth2Token" → Tokens: ["oauth", "2", "token"]

// Scoring algorithm
// - Exact token match: 10 points
// - Prefix match: 8 points
// - Substring match: 6 points
// - Direct text inclusion: 5 points
// - N-gram fuzzy match: 0.5-3 points
// - Multi-token bonus: +5 points per additional match
// - Position bonus: +3 points for first-word match

// Example searches that work well
await client.callTool({
  name: 'search_twitterapi_docs',
  arguments: { query: 'getUserFollowers' }  // Matches get_user_followers
});

await client.callTool({
  name: 'search_twitterapi_docs',
  arguments: { query: 'webhook filter' }  // Matches webhook filter rules
});

await client.callTool({
  name: 'search_twitterapi_docs',
  arguments: { query: 'rate limit' }  // Matches QPS limits documentation
});
```

## Hybrid Caching System

The server uses memory-first caching with disk persistence for optimal performance across MCP sessions.

```javascript
// Cache configuration
const searchCache = new HybridCache('search', {
  maxEntries: 200,
  ttl: 6 * 60 * 60 * 1000,     // 6 hours
  diskWriteProbability: 1.0     // Always persist to disk
});

const endpointCache = new HybridCache('endpoints', {
  maxEntries: 100,
  ttl: 24 * 60 * 60 * 1000,    // 24 hours
  diskWriteProbability: 1.0
});

// Cache lookup flow
// 1. Check memory cache (instant)
// 2. Check disk cache (fast)
// 3. Execute query (slower)
// 4. Store in memory + disk

// Cache cleanup runs hourly
// - Removes expired entries from memory
// - Removes expired files from disk
// - LRU eviction when memory exceeds capacity
```

## Development and Testing

Running the development environment and test suite.

```bash
# Clone and setup
git clone https://github.com/dorukardahan/twitterapi-io-mcp.git
cd twitterapi-io-mcp
npm install

# Run 48 unit tests
npm test

# Start server locally
npm start

# Update documentation snapshot
node scrape-all.cjs

# Test with MCP inspector
npx @modelcontextprotocol/inspector node index.js
```

```javascript
// Test structure (from test/index.test.js)
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Integration test example
const transport = new StdioClientTransport({
  command: process.execPath,
  args: ['index.js']
});

const client = new Client({
  name: 'test-client',
  version: '1.0.0'
});

await client.connect(transport);
const tools = await client.listTools();
const result = await client.callTool({
  name: 'get_twitterapi_pricing',
  arguments: {}
});
await client.close();
```

## Summary

This MCP server provides comprehensive offline access to TwitterAPI.io documentation through seven specialized tools and multiple resource endpoints. The search tool supports advanced fuzzy matching with camelCase tokenization, while specific tools like `get_twitterapi_endpoint` and `get_twitterapi_guide` provide detailed information retrieval. The hybrid caching system ensures fast responses across MCP sessions by combining memory and disk persistence with 6-24 hour TTLs.

The server is designed for integration with AI assistants like Claude, enabling natural language queries about Twitter API endpoints, authentication, pricing, and rate limits without leaving the conversation context. With 54 documented endpoints across 9 categories, structured content outputs for better LLM parsing, and production-ready features like SLO tracking and data freshness monitoring, it serves as a complete reference implementation for building MCP documentation servers. Install it globally with `npx -y twitterapi-io-mcp` or add it to Claude Desktop configuration for instant access to all TwitterAPI.io documentation.