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

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:

Claude Desktop

Add the following to your Claude Desktop configuration:

For NPM installation:

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

For local/source installation:

First build the project:

Then add to Claude Desktop config:

Running Standalone

You can also run the server standalone for testing:

Using with MCP Inspector

Test the server using the MCP Inspector:

Example Queries

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

• "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"
• "Use Astro MCP to get keywords for app ID 987654321"

Database Requirements

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

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 (pure JavaScript, read-only access to Astro's database)
• 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)

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
• ZRATING - App ratings
• ZRATINGDATAPOINT - Historical rating data

Development

Project Structure

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 LICENSE 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. "Wrong Node.js version" error
   • Ensure you're using Node.js 18 or higher
   • For nvm users: Check that npx is using the correct Node version:
     npx node --version # Should show v18.x.x or higher which npx # Should be in your nvm directory
   • If npx is using the wrong version, reinstall npm after switching:
     nvm use 18 npm install -g npm
4. No data returned
   • 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')

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