daoleno/lens-mcp

Lens Protocol MCP Server

A Model Context Protocol (MCP) server that provides agent-optimized access to Lens Protocol data and functionality.

🛠️ Available Tools

lens_search

When you need to find or discover anything on Lens Protocol

• Find: Accounts, posts, usernames, apps, and groups
• Natural Language: "crypto accounts", "DeFi posts", "popular apps"
• Example: lens_search(query="vitalik", type="accounts", show="concise")

lens_profile

When you want to learn everything about a Lens Protocol account

• Comprehensive Analysis: Identity, social connections, influence, and activity with posts
• Include Options: basic, social, influence, activity (includes posts), network
• Example: lens_profile(who="0x...", include=["basic", "activity"], analyze="influence")

lens_content

When you want to understand how content performs and what people think about it

• Content Analysis: Posts, reactions, comments, engagement metrics
• Natural Queries: "reactions to this post", "popular posts by user"
• Example: lens_content(about="reactions", target="post_123", include=["likes", "comments"])

lens_ecosystem

When you want to explore the broader Lens Protocol ecosystem

• Ecosystem Views: Trending content, popular applications, platform statistics
• Community Insights: Apps, groups, ecosystem health, growth areas
• Example: lens_ecosystem(view="trending", timeframe="7d", show="detailed")

Resources (Data Access)

• lens://account/{address} - Account/profile information
• lens://post/{id} - Post/publication data
• lens://app/{address} - Application information
• lens://group/{address} - Group information

📋 Response Formats

Concise (Default)

Natural language summaries optimized for AI understanding:

🔍 Found 5 accounts matching "blockchain":
• vitalik.lens (0x1234...)
• ethereum.lens (0x5678...)
• defi.lens (0x9abc...)
... and 2 more

Detailed

Summary + complete JSON data for full context:

🔍 Found 5 accounts matching "blockchain":
• vitalik.lens (0x1234...)
...

{
  "items": [...],
  "pageInfo": {...}
}

Raw

Direct JSON output for programmatic use:

{
  "items": [...],
  "pageInfo": {...}
}

🎯 Usage Examples

Search for Accounts

{
  "name": "lens_search",
  "arguments": {
    "query": "vitalik",
    "type": "accounts",
    "show": "concise",
    "limit": 10
  }
}

Analyze Profile with Activity and Social Data

{
  "name": "lens_profile",
  "arguments": {
    "who": "0x...",
    "include": ["basic", "activity", "social"],
    "show": "detailed"
  }
}

Understand Content Engagement

{
  "name": "lens_content",
  "arguments": {
    "what": "reactions to this post",
    "about": "reactions", 
    "target": "post_123",
    "include": ["likes", "comments"]
  }
}

Explore Ecosystem Trends

{
  "name": "lens_ecosystem",
  "arguments": {
    "view": "trending",
    "timeframe": "7d",
    "show": "detailed"
  }
}

Installation

bun install

Usage

Starting the Server

Local (stdio) Mode

bun start

Remote HTTP Mode

bun start:http
# Or with custom port
PORT=8080 bun start:http

The server supports both stdio (for local use) and HTTP (for remote access) transports.

Configuration

Set environment variables:

• LENS_ENVIRONMENT: Set to "testnet" for testnet, defaults to mainnet
• PORT: HTTP server port (default: 3000)

MCP Client Configuration

Local Server Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "lens-protocol": {
      "command": "bun",
      "args": ["index.ts"],
      "cwd": "/path/to/lens-mcp"
    }
  }
}

Remote Server Configuration

For remote HTTP access:

{
  "mcpServers": {
    "lens-protocol-remote": {
      "transport": {
        "type": "http",
        "url": "https://lens-mcp.wooo.guru/mcp"
      }
    }
  }
}

Development

Running in Development Mode

# Stdio mode
bun dev

# HTTP mode  
bun dev:http

Testing

# Run unit tests
bun test

# Run integration tests  
bun test:integration

# Run all tests
bun test:all

Docker Deployment

# Build and run with Docker
docker build -f docker/Dockerfile -t lens-mcp .
docker run -p 3000:3000 lens-mcp

# Or use docker-compose
docker-compose -f docker/docker-compose.yml up

🏗️ Architecture & Design Principles

Built With

• @lens-protocol/client@canary - Official Lens Protocol TypeScript SDK
• @modelcontextprotocol/sdk - MCP server implementation
• Bun - Fast JavaScript runtime and package manager

Design Principles

1. Workflow-Focused: Tools match natural task subdivisions
2. Context Efficient: Built-in token limits and smart pagination
3. Natural Language: Returns semantic summaries by default
4. Actionable Errors: Error messages include specific guidance
5. Multiple Formats: Choose between concise, detailed, or raw output

Limitations

• Search functionality is limited in public client mode (requires authenticated session)
• Some advanced features require authentication which is not implemented in this server
• Rate limiting depends on Lens Protocol API limits

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes
4. Test with bun test.ts
5. Submit a pull request

License

MIT License