withtally/mcp-tally-api

MCP Tally API

A Model Context Protocol (MCP) server that provides LLMs with access to Tally's blockchain governance API for querying DAOs, proposals, and voting data across multiple networks.

🚀 Quick Start

Get started with MCP Tally API in Cursor or Claude Desktop in 2 minutes:

1. Get a Tally API Key

Sign up at Tally.xyz to get your free API key.

2. Install the MCP Server

npm install -g mcp-tally-api

3. Configure Cursor/Claude Desktop

Add to your MCP configuration file:

Cursor: Edit .cursor/mcp.json in your project:

{
  "servers": {
    "tally": {
      "command": "mcp-tally-api",
      "env": {
        "TALLY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop: Edit claude_desktop_config.json:

{
  "mcpServers": {
    "tally": {
      "command": "mcp-tally-api",
      "env": {
        "TALLY_API_KEY": "your_api_key_here"
      }
    }
  }
}

4. Start Using

Restart Cursor/Claude Desktop and start asking about DAOs:

"What are the most popular DAOs with active proposals?"
"Show me details about Uniswap governance"
"Who are the top delegates in Arbitrum DAO?"

🎯 You now have access to 14 tools and 7 resources for comprehensive DAO governance analysis!

Features

🚀 Features

• 🔧 Tools: 14 comprehensive tools for querying organizations, proposals, users, and delegates
• 📚 Resources: 7 browsable resources including Popular DAOs mapping and governance overviews
• 🎯 Prompts: 6 governance-focused prompt templates for structured DAO analysis
• ⚡ Real-time: Live data from Tally's GraphQL API with proper error handling
• 🔍 Filtering: Advanced filtering, sorting, and pagination across all endpoints
• 🌐 Multi-chain: Support for 15+ blockchain networks including Ethereum, Polygon, Arbitrum
• 📊 Rich Data: Comprehensive governance metrics, voting patterns, and delegate information

🏛️ Organization Management

• list_organizations: Browse DAOs with pagination, filtering by chain/logo, and sorting by popularity
• get_organization: Get detailed DAO information including member counts and proposal statistics
• get_organizations_with_active_proposals: Find DAOs with ongoing governance activity

📊 Proposal Operations

• list_proposals: View proposals for specific DAOs with filtering and sorting options
• get_proposal: Get detailed proposal information including voting statistics and execution details
• get_active_proposals: Find active proposals across all DAOs or filtered by criteria

👥 User & Delegation

• get_user_daos: Discover which DAOs a user participates in
• get_dao_participants: List members of a specific DAO with sorting options
• get_user_details: Get comprehensive user information and governance activity
• get_delegates: Find delegates in a DAO with delegation statistics

📚 Resources

• Popular DAOs: Stable mapping of 20 major DAOs to their organization IDs across 5 networks
• Server Info: Runtime information and health status
• Organization Overview: Human-readable markdown overviews of DAOs via tally://org/{organizationId}
• Proposal Overview: Detailed proposal information via tally://org/{organizationId}/proposal/{proposalId}
• User Profile Overview: Governance profiles via tally://user/{address}
• Trending Proposals: Active governance activity via tally://trending/proposals

🔗 Resource Templates

Resource templates provide browsable, AI-friendly access to governance data:

Organization Overview (tally://org/{organizationId})

Get human-readable markdown overviews of any DAO:

URI: tally://org/2206072050458560434
Content-Type: text/markdown

# Uniswap

**Description:** Uniswap is a decentralized protocol for automated liquidity provision on Ethereum.

## 📊 Key Metrics

- **Members:** 47,543
- **Total Proposals:** 81
- **Active Proposals:** 0
- **Chain:** eip155:1

## 🏛️ Governance Status

**Current Activity:** 🔵 No active proposals

## 🔗 Links

[Website](https://uniswap.org) • [Twitter](https://twitter.com/Uniswap) • [GitHub](https://github.com/Uniswap)

---
*Data from Tally API • Organization ID: 2206072050458560434 • Slug: uniswap*

Proposal Overview (tally://org/{organizationId}/proposal/{proposalId})

Get detailed markdown overviews of specific proposals:

URI: tally://org/2206072050458560434/proposal/2589356045239322076
Content-Type: text/markdown

# ❌ Scaling V4 and Supporting Unichain

**Organization:** Uniswap

## 📋 Proposal Details

- **Status:** Defeated
- **Proposal ID:** 2589356045239322076
- **Proposer:** `0x9B68c14e936104e9a7a24c712BEecdc220002984`
- **Start Time:** May 12, 2025 at 09:18 PM
- **End Time:** May 18, 2025 at 01:20 PM

## 📄 Description

# Scaling V4 and Supporting Unichain
PGOV is submitting the proposal on GFX Labs' behalf...

## 🗳️ Voting Results

- **For:** 24.7M votes
- **Against:** 3.0K votes
- **Abstain:** 5.3M votes

## ⚙️ Execution

⏳ **Status:** Not executed

---
*Data from Tally API • Organization ID: 2206072050458560434 • Proposal ID: 2589356045239322076*

User Profile Overview (tally://user/{address})

Get governance profiles for any Ethereum address:

URI: tally://user/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
Content-Type: text/markdown

# 👤 Anonymous User

## 📋 Profile Details

- **Address:** `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`

## 🏛️ DAO Participation

*No DAO participation found for this address.*

---
*Data from Tally API • Address: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045*

Trending Proposals (tally://trending/proposals)

Get an overview of active governance across all DAOs:

URI: tally://trending/proposals
Content-Type: text/markdown

# 🔥 Trending Governance Activity

**0 Active Proposal(s) Across All DAOs**

*No active proposals found at this time.*

Check back later for ongoing governance activity!

---
*Data from Tally API • Updated: 5/28/2025, 12:24:27 AM*

Benefits:

• Browsable: AI can explore governance data like reading documents
• Cacheable: Popular resources can be cached for performance
• Linkable: Easy to reference specific governance data in conversations
• Readable: Returns human-friendly markdown format
• Error-Safe: Graceful error handling for invalid parameters
• Real-time: Always shows current data from the live Tally API

🎯 Prompt Templates

Governance-focused prompt templates that guide LLMs through comprehensive DAO analysis:

DAO Analysis (analyze-dao-governance)

Complete governance health assessment for any DAO:

Parameters:
- organizationId: The DAO to analyze
- includeComparison: Whether to compare with similar DAOs (optional)

Guides LLM through:
- Organization overview and metrics
- Active governance activity analysis  
- Delegate distribution and voting power
- Recent proposal patterns and success rates
- Optional peer comparison and benchmarking

DAO Comparison (compare-dao-governance)

Side-by-side governance comparison between two DAOs:

Parameters:
- dao1: First DAO organization ID or slug
- dao2: Second DAO organization ID or slug  
- aspect: Focus area (overall, delegates, proposals, activity)

Provides structured comparison framework for:
- Quantitative metrics and participation rates
- Governance quality and community health
- Structural differences and best practices
- Actionable recommendations for improvement

Delegate Research (analyze-delegate-profile)

Comprehensive delegate profiling and analysis:

Parameters:
- address: Ethereum address of the delegate
- organizationId: Specific DAO to focus on (optional)

Research framework covering:
- Cross-DAO governance experience and history
- Current voting power and delegation status
- Participation quality and voting consistency
- Community standing and delegate statements
- Specialization areas and expertise

Trend Discovery (discover-governance-trends)

Ecosystem-wide governance trend analysis:

Parameters:
- timeframe: Analysis focus (current, recent, emerging)
- category: DAO category filter (all, defi, infrastructure, social)

Trend analysis covering:
- Governance innovation and new mechanisms
- Hot topics and common proposal themes
- Participation patterns and delegate activity
- Cross-DAO movements and coordination

DAO Recommendations (find-dao-to-join)

Personalized DAO discovery and recommendations:

Parameters:
- interests: Focus areas (comma-separated, e.g., "DeFi,gaming")
- participationLevel: Desired engagement (observer, voter, delegate, contributor)
- experience: Governance experience (beginner, intermediate, expert)

Matching framework considering:
- Interest alignment with DAO focus areas
- Participation opportunities and entry barriers
- Experience-appropriate complexity levels
- Community health and governance quality

Proposal Analysis (analyze-proposal)

In-depth proposal analysis and voting guidance:

Parameters:
- organizationId: DAO where the proposal exists
- proposalId: Specific proposal to analyze

Analysis framework covering:
- Proposal details and strategic implications
- Current voting dynamics and participation
- Key delegate positions and influence
- Risk assessment and implementation challenges
- Voting recommendations and considerations

Benefits:

• Structured Guidance: Step-by-step instructions for thorough analysis
• Tool Integration: Optimized use of all Tally API tools and resources
• Flexible Focus: Customizable analysis depth and comparison scope
• Actionable Insights: Designed to produce practical recommendations

⚡ Advanced Query Capabilities

For power users who need access to functionality beyond the pre-built tools, the MCP Tally API server provides direct access to the underlying GraphQL API:

execute_graphql_query Tool

Execute arbitrary GraphQL queries against the Tally API:

Parameters:
- query: GraphQL query string
- variables: Optional variables for the GraphQL query

Example:
Query: "query GetOrganizations { organizations(input: { page: { limit: 3 } }) { nodes { ... on Organization { id name slug chainIds } } } }"

Response: Raw GraphQL response data with full access to any Tally API functionality

tally-api-schema Resource

Get the complete GraphQL schema via introspection:

URI: tally://api/schema
Content-Type: application/json

Returns: Complete GraphQL schema including all types, fields, mutations, enums, and directives

Benefits:

• Unlimited Access: Query any data available in the Tally GraphQL API
• Real Schema: Always up-to-date schema directly from the API via introspection
• Custom Queries: Build specialized queries for unique use cases
• Development Aid: Full schema documentation for building custom integrations
• Future-Proof: Access new Tally API features before they're added as dedicated tools

Use Cases:

• Research specific governance patterns not covered by existing tools
• Build custom analysis workflows with specialized data requirements
• Access experimental or beta Tally API features
• Create complex aggregations across multiple data sources
• Debug and understand the underlying API structure

Quick Start

Prerequisites

• Bun runtime
• Tally API key from Tally.xyz

Installation

Option 1: Install from npm (Recommended)

# Install globally
npm install -g mcp-tally-api

# Or install locally in your project
npm install mcp-tally-api

# Set up environment
echo "TALLY_API_KEY=your_api_key_here" > .env

Option 2: Build from source

# Clone and install
git clone https://github.com/withtally/mcp-tally-api.git
cd mcp-tally-api
bun install

# Set up environment
echo "TALLY_API_KEY=your_api_key_here" > .env

# Build and test
bun run build
bun run test