Skip to main content
Glama

Astro MCP Server

by TimBroddin
README.md10.3 kB
# Astro MCP Server An MCP (Model Context Protocol) server that provides access to [Astro](https://tryastro.app/) ASO (App Store Optimization) data for LLMs. ![Astro MCP Server Example](example.jpg) ## Requirements - [Astro](https://tryastro.app/) - 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 ```bash # Check your Node version node --version ``` ## Usage with Claude ### Claude Code (Recommended) The easiest way to use this MCP server is with Claude Code: ```bash # 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`: ```json { "mcpServers": { "astro-aso": { "command": "npx", "args": ["-y", "astro-mcp-server"] } } } ``` **For local/source installation:** First build the project: ```bash cd /path/to/astro-mcp-server npm run build ``` Then add to Claude Desktop config: ```json { "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: ```bash # 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: ```bash # 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 [LICENSE](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. **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](https://broddin.be) - Available for hire at [Titans of Industry](https://titansofindustry.be)*

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/TimBroddin/astro-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server