TimBroddin/astro-mcp-server

Astro MCP Server

An MCP (Model Context Protocol) server that provides access to Astro ASO (App Store Optimization) data for LLMs.

Requirements

• Astro
• A tool with MCP support (Claude Desktop, Claude Code, ...)

Features

This MCP server provides the following tools for querying Astro's ASO database:

Available Tools

1. search_rankings - Search current keyword rankings for apps

   • Find how apps rank for specific keywords
   • Filter by app store (us, uk, etc.)
   • Filter by app name or app ID

2. get_historical_rankings - Get historical ranking data

   • Track ranking changes over time
   • Configurable time period (default: 30 days)
   • Filter by app and store

3. list_apps - List all tracked applications

   • Shows app names, IDs, platforms
   • Includes keyword count per app

4. get_app_keywords - Get all keywords for a specific app

   • Shows current and previous rankings
   • Includes difficulty and popularity scores
   • Shows ranking changes
   • Accepts app name or app ID

5. get_keyword_trends - Analyze ranking trends

   • Statistical analysis (avg, min, max, volatility)
   • Trend detection (improving/declining/stable)
   • Configurable periods (week/month/year/all)

6. compare_rankings - Compare rankings between dates

   • Find ranking changes between two specific dates
   • Calculate percentage changes

7. get_app_ratings - Get app rating history

   • Track rating changes over time
   • Shows user rating counts
   • Accepts app name or app ID

8. get_keyword_competitors - Get real App Store competitors for keywords

   • Shows actual competitor apps from App Store data with app categories
   • Rankings based on real App Store search results
   • Multi-store support with automatic data aggregation
   • Configurable limit for number of competitors returned

9. get_keyword_recommendations - Get keyword recommendations

   • Suggests related keywords based on existing tracking data
   • Helps discover new keyword opportunities
   • Fuzzy matching for broader keyword discovery

10. analyze_competitive_landscape - Comprehensive competitive analysis

    • Identifies top competitors across all tracked keywords with app categories
    • Calculates market share metrics (top 10/25/50 rankings)
    • Shows competitor dominance scores and shared keywords
    • Assesses competitive intensity levels
    • Configurable limit for number of competitors returned

11. calculate_keyword_opportunity - Find keyword opportunities

    • Identifies high-opportunity keywords with low competition
    • Combines popularity, difficulty, and competition metrics
    • Configurable thresholds for targeted opportunity discovery
    • Provides reasoning for each opportunity score

12. detect_ranking_anomalies - Detect unusual ranking changes

    • Identifies sudden ranking drops, rises, and volatility spikes
    • Provides context about timing and previous rankings
    • Categorizes anomaly severity (low/medium/high/critical)
    • Includes interpretation of ranking changes

13. predict_ranking_trends - Predict future ranking movements

    • Uses linear regression to forecast ranking trajectories
    • Provides confidence scores and trend directions
    • Estimates future ranking positions based on historical data
    • Shows methodology and data points used for predictions

14. find_low_competition_keywords - Discover underutilized keywords

    • Finds keywords with low competition scores
    • Balances difficulty vs. popularity for optimal targeting
    • Helps identify niche market opportunities
    • Configurable parameters for precise filtering

Installation

Prerequisites

• Astro app must be installed on your Mac with data in its database
• Node.js 18+ required

  # Check your Node version
  node --version
  

Usage with Claude

Claude Code (Recommended)

The easiest way to use this MCP server is with Claude Code:

# Install from NPM
claude mcp add -s user -t stdio astro -- npx -y astro-mcp-server

# If npx is using the wrong Node version (common with nvm), use the full path:
claude mcp add -s user -t stdio astro -- $(which npx) -y astro-mcp-server

# Or for local/source installation (after building):
claude mcp add -s user -t stdio astro -- node /path/to/astro-mcp-server/dist/index.js

Claude Desktop

Add the following to your Claude Desktop configuration:

For NPM installation:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "astro-aso": {
      "command": "npx",
      "args": ["-y", "astro-mcp-server"]
    }
  }
}

For local/source installation:

First build the project:

cd /path/to/astro-mcp-server
npm run build

Then add to Claude Desktop config:

{
  "mcpServers": {
    "astro-aso": {
      "command": "node",
      "args": ["/path/to/astro-mcp-server/dist/index.js"]
    }
  }
}

Running Standalone

You can also run the server standalone for testing:

# If installed globally
astro-mcp-server

# Or run with npx
npx astro-mcp-server

# Or from source (after building)
npm run build
npm start

# Or for development with auto-reload
npm run dev

Using with MCP Inspector

Test the server using the MCP Inspector:

# For NPM installation
npx @modelcontextprotocol/inspector npx astro-mcp-server

# For local installation (after building)
npx @modelcontextprotocol/inspector node /path/to/dist/index.js

Example Queries

Once connected to Claude (via Claude Code or Claude Desktop), you can ask questions like:

Basic Queries:

• "Use Astro MCP to show the current rankings for the keyword 'productivity' in the US store"
• "Use Astro MCP to show me the ranking trends for 'task manager' over the last month"
• "Use Astro MCP to list all the apps being tracked"
• "Use Astro MCP to show what keywords the app 'Things 3' ranks for"
• "Use Astro MCP to compare rankings for 'notes' between last week and today"
• "Use Astro MCP to show me the rating history for app ID 1234567890"

Advanced Competitive Intelligence:

• "Use Astro MCP to show me the real App Store competitors for the keyword 'meditation' with their categories"
• "Use Astro MCP to analyze the competitive landscape for my app in the productivity space, showing top 15 competitors"
• "Use Astro MCP to find keyword opportunities with low competition and high popularity"
• "Use Astro MCP to detect any ranking anomalies in my app's performance this week"
• "Use Astro MCP to predict where my 'todo app' keyword will rank next month"
• "Use Astro MCP to find low-competition keywords I should target for my wellness app"
• "Use Astro MCP to get keyword recommendations based on my current 'fitness' keyword"

Database Requirements

The server requires read access to Astro's SQLite database, typically located at:

~/Library/Containers/matteospada.it.ASO/Data/Library/Application Support/Astro/Model.sqlite

Make sure Astro has been run at least once and has collected some data before using this server.

Technical Details

• Runtime: Node.js 18+
• Database: SQLite via sql.js (JavaScript implementation, no native compilation required)
• Database Loading: Automatically detects and reloads database changes, including WAL mode support with checkpoint forcing
• Protocol: MCP (Model Context Protocol) via stdio
• TypeScript: Compiled to JavaScript for distribution
• Date Handling: Converts Core Data timestamps to ISO format
• App Identification: Supports both app names (partial matching) and app IDs (exact matching)
• WAL Mode Support: Automatically handles Write-Ahead Logging mode databases by forcing checkpoints to merge recent changes

Database Schema

The server reads from these main tables in Astro's database:

• ZAPPLICATION - App information
• ZKEYWORD - Keywords and current rankings
• ZDATAPOINT - Historical ranking data points
• ZBINARYDATA - Real App Store competitor data (JSON format)
• ZRATING - App ratings
• ZRATINGDATAPOINT - Historical rating data

Development

Project Structure

astro-mcp-server/
├── src/
│   ├── index.ts      # Main server implementation
│   └── types.ts      # TypeScript type definitions
├── package.json      # Dependencies
├── tsconfig.json     # TypeScript config
├── mcp.json         # MCP configuration
└── README.md        # This file

Building from Source

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Run in development mode: npm run dev

Publishing to NPM

1. Update version in package.json
2. Update author and repository URLs in package.json
3. Run: npm publish (automatically builds via prepublishOnly)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT - See file for details

Troubleshooting

Common Issues

1. "Database not found" error

   • Ensure Astro is installed and has been run at least once
   • Check that the database path exists

2. "Permission denied" error

   • The server needs read access to Astro's database
   • Check file permissions on the SQLite database

3. Node.js compatibility

   • Ensure you're using Node.js 18 or higher
   • The server uses sql.js (pure JavaScript), so no native module compilation is required
   • This eliminates NODE_MODULE_VERSION errors that were common with better-sqlite3

4. No data returned or stale data

   • Ensure Astro has collected keyword tracking data
   • Check that you're using the correct app names or IDs
   • Verify the store parameter (default is 'us')
   • The server automatically reloads the database when changes are detected
   • For WAL mode databases, recent changes are merged automatically via checkpoints

Support

For issues or questions, please open an issue on GitHub.

This project was vibecoded with ❤️ by Tim Broddin - Available for hire at Titans of Industry