{"id":31045561,"url":"https://github.com/timbroddin/astro-mcp-server","last_synced_at":"2025-09-17T20:03:14.361Z","repository":{"id":314243153,"uuid":"1054733581","full_name":"TimBroddin/astro-mcp-server","owner":"TimBroddin","description":"An MCP (Model Context Protocol) server that provides access to Astro ASO (App Store Optimization) data for LLMs.","archived":false,"fork":false,"pushed_at":"2025-09-12T14:40:36.000Z","size":604,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T17:02:11.526Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimBroddin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T08:59:02.000Z","updated_at":"2025-09-12T14:40:40.000Z","dependencies_parsed_at":"2025-09-11T11:47:13.241Z","dependency_job_id":"6dc942a7-56b9-4d68-932c-bc4ca9c9c7f5","html_url":"https://github.com/TimBroddin/astro-mcp-server","commit_stats":null,"previous_names":["timbroddin/astro-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TimBroddin/astro-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBroddin%2Fastro-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBroddin%2Fastro-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBroddin%2Fastro-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBroddin%2Fastro-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimBroddin","download_url":"https://codeload.github.com/TimBroddin/astro-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimBroddin%2Fastro-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275136762,"owners_count":25411709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-14T17:01:57.498Z","updated_at":"2025-09-15T18:03:07.179Z","avatar_url":"https://github.com/TimBroddin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Astro MCP Server\n\nAn MCP (Model Context Protocol) server that provides access to [Astro](https://tryastro.app/) ASO (App Store Optimization) data for LLMs.\n\n![Astro MCP Server Example](example.jpg)\n\n## Requirements\n\n- [Astro](https://tryastro.app/)\n- A tool with MCP support (Claude Desktop, Claude Code, ...)\n\n## Features\n\nThis MCP server provides the following tools for querying Astro's ASO database:\n\n### Available Tools\n\n1. **search_rankings** - Search current keyword rankings for apps\n   - Find how apps rank for specific keywords\n   - Filter by app store (us, uk, etc.)\n   - Filter by app name or app ID\n\n2. **get_historical_rankings** - Get historical ranking data\n   - Track ranking changes over time\n   - Configurable time period (default: 30 days)\n   - Filter by app and store\n\n3. **list_apps** - List all tracked applications\n   - Shows app names, IDs, platforms\n   - Includes keyword count per app\n\n4. **get_app_keywords** - Get all keywords for a specific app\n   - Shows current and previous rankings\n   - Includes difficulty and popularity scores\n   - Shows ranking changes\n   - Accepts app name or app ID\n\n5. **get_keyword_trends** - Analyze ranking trends\n   - Statistical analysis (avg, min, max, volatility)\n   - Trend detection (improving/declining/stable)\n   - Configurable periods (week/month/year/all)\n\n6. **compare_rankings** - Compare rankings between dates\n   - Find ranking changes between two specific dates\n   - Calculate percentage changes\n\n7. **get_app_ratings** - Get app rating history\n   - Track rating changes over time\n   - Shows user rating counts\n   - Accepts app name or app ID\n\n8. **get_keyword_competitors** - Get real App Store competitors for keywords\n   - Shows actual competitor apps from App Store data with app categories\n   - Rankings based on real App Store search results\n   - Multi-store support with automatic data aggregation\n   - Configurable limit for number of competitors returned\n\n9. **get_keyword_recommendations** - Get keyword recommendations\n   - Suggests related keywords based on existing tracking data\n   - Helps discover new keyword opportunities\n   - Fuzzy matching for broader keyword discovery\n\n10. **analyze_competitive_landscape** - Comprehensive competitive analysis\n    - Identifies top competitors across all tracked keywords with app categories\n    - Calculates market share metrics (top 10/25/50 rankings)\n    - Shows competitor dominance scores and shared keywords\n    - Assesses competitive intensity levels\n    - Configurable limit for number of competitors returned\n\n11. **calculate_keyword_opportunity** - Find keyword opportunities\n    - Identifies high-opportunity keywords with low competition\n    - Combines popularity, difficulty, and competition metrics\n    - Configurable thresholds for targeted opportunity discovery\n    - Provides reasoning for each opportunity score\n\n12. **detect_ranking_anomalies** - Detect unusual ranking changes\n    - Identifies sudden ranking drops, rises, and volatility spikes\n    - Provides context about timing and previous rankings\n    - Categorizes anomaly severity (low/medium/high/critical)\n    - Includes interpretation of ranking changes\n\n13. **predict_ranking_trends** - Predict future ranking movements\n    - Uses linear regression to forecast ranking trajectories\n    - Provides confidence scores and trend directions\n    - Estimates future ranking positions based on historical data\n    - Shows methodology and data points used for predictions\n\n14. **find_low_competition_keywords** - Discover underutilized keywords\n    - Finds keywords with low competition scores\n    - Balances difficulty vs. popularity for optimal targeting\n    - Helps identify niche market opportunities\n    - Configurable parameters for precise filtering\n\n## Installation\n\n### Prerequisites\n\n- **Astro** app must be installed on your Mac with data in its database\n- **Node.js** 18+ required\n  ```bash\n  # Check your Node version\n  node --version\n  ```\n  \n\n## Usage with Claude\n\n### Claude Code (Recommended)\n\nThe easiest way to use this MCP server is with Claude Code:\n\n```bash\n# Install from NPM\nclaude mcp add -s user -t stdio astro -- npx -y astro-mcp-server\n\n# If npx is using the wrong Node version (common with nvm), use the full path:\nclaude mcp add -s user -t stdio astro -- $(which npx) -y astro-mcp-server\n\n# Or for local/source installation (after building):\nclaude mcp add -s user -t stdio astro -- node /path/to/astro-mcp-server/dist/index.js\n```\n\n### Claude Desktop\n\nAdd the following to your Claude Desktop configuration:\n\n**For NPM installation:**\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"astro-aso\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"astro-mcp-server\"]\n    }\n  }\n}\n```\n\n**For local/source installation:**\n\nFirst build the project:\n```bash\ncd /path/to/astro-mcp-server\nnpm run build\n```\n\nThen add to Claude Desktop config:\n```json\n{\n  \"mcpServers\": {\n    \"astro-aso\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/astro-mcp-server/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Running Standalone\n\nYou can also run the server standalone for testing:\n\n```bash\n# If installed globally\nastro-mcp-server\n\n# Or run with npx\nnpx astro-mcp-server\n\n# Or from source (after building)\nnpm run build\nnpm start\n\n# Or for development with auto-reload\nnpm run dev\n```\n\n### Using with MCP Inspector\n\nTest the server using the MCP Inspector:\n\n```bash\n# For NPM installation\nnpx @modelcontextprotocol/inspector npx astro-mcp-server\n\n# For local installation (after building)\nnpx @modelcontextprotocol/inspector node /path/to/dist/index.js\n```\n\n### Example Queries\n\nOnce connected to Claude (via Claude Code or Claude Desktop), you can ask questions like:\n\n**Basic Queries:**\n- \"Use Astro MCP to show the current rankings for the keyword 'productivity' in the US store\"\n- \"Use Astro MCP to show me the ranking trends for 'task manager' over the last month\"\n- \"Use Astro MCP to list all the apps being tracked\"\n- \"Use Astro MCP to show what keywords the app 'Things 3' ranks for\"\n- \"Use Astro MCP to compare rankings for 'notes' between last week and today\"\n- \"Use Astro MCP to show me the rating history for app ID 1234567890\"\n\n**Advanced Competitive Intelligence:**\n- \"Use Astro MCP to show me the real App Store competitors for the keyword 'meditation' with their categories\"\n- \"Use Astro MCP to analyze the competitive landscape for my app in the productivity space, showing top 15 competitors\"\n- \"Use Astro MCP to find keyword opportunities with low competition and high popularity\"\n- \"Use Astro MCP to detect any ranking anomalies in my app's performance this week\"\n- \"Use Astro MCP to predict where my 'todo app' keyword will rank next month\"\n- \"Use Astro MCP to find low-competition keywords I should target for my wellness app\"\n- \"Use Astro MCP to get keyword recommendations based on my current 'fitness' keyword\"\n\n## Database Requirements\n\nThe server requires read access to Astro's SQLite database, typically located at:\n```\n~/Library/Containers/matteospada.it.ASO/Data/Library/Application Support/Astro/Model.sqlite\n```\n\nMake sure Astro has been run at least once and has collected some data before using this server.\n\n## Technical Details\n\n- **Runtime**: Node.js 18+\n- **Database**: SQLite via sql.js (JavaScript implementation, no native compilation required)\n- **Database Loading**: Automatically detects and reloads database changes, including WAL mode support with checkpoint forcing\n- **Protocol**: MCP (Model Context Protocol) via stdio\n- **TypeScript**: Compiled to JavaScript for distribution\n- **Date Handling**: Converts Core Data timestamps to ISO format\n- **App Identification**: Supports both app names (partial matching) and app IDs (exact matching)\n- **WAL Mode Support**: Automatically handles Write-Ahead Logging mode databases by forcing checkpoints to merge recent changes\n\n## Database Schema\n\nThe server reads from these main tables in Astro's database:\n\n- `ZAPPLICATION` - App information\n- `ZKEYWORD` - Keywords and current rankings\n- `ZDATAPOINT` - Historical ranking data points\n- `ZBINARYDATA` - Real App Store competitor data (JSON format)\n- `ZRATING` - App ratings  \n- `ZRATINGDATAPOINT` - Historical rating data\n\n## Development\n\n### Project Structure\n\n```\nastro-mcp-server/\n├── src/\n│   ├── index.ts      # Main server implementation\n│   └── types.ts      # TypeScript type definitions\n├── package.json      # Dependencies\n├── tsconfig.json     # TypeScript config\n├── mcp.json         # MCP configuration\n└── README.md        # This file\n```\n\n### Building from Source\n\n1. Clone the repository\n2. Install dependencies: `npm install`\n3. Build the project: `npm run build`\n4. Run in development mode: `npm run dev`\n\n### Publishing to NPM\n\n1. Update version in `package.json`\n2. Update author and repository URLs in `package.json`\n3. Run: `npm publish` (automatically builds via prepublishOnly)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT - See [LICENSE](LICENSE) file for details\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Database not found\" error**\n   - Ensure Astro is installed and has been run at least once\n   - Check that the database path exists\n\n2. **\"Permission denied\" error**\n   - The server needs read access to Astro's database\n   - Check file permissions on the SQLite database\n\n3. **Node.js compatibility**\n   - Ensure you're using Node.js 18 or higher\n   - The server uses sql.js (pure JavaScript), so no native module compilation is required\n   - This eliminates NODE_MODULE_VERSION errors that were common with better-sqlite3\n\n4. **No data returned or stale data**\n   - Ensure Astro has collected keyword tracking data\n   - Check that you're using the correct app names or IDs\n   - Verify the store parameter (default is 'us')\n   - The server automatically reloads the database when changes are detected\n   - For WAL mode databases, recent changes are merged automatically via checkpoints\n\n## Support\n\nFor issues or questions, please open an issue on GitHub.\n\n---\n\n*This project was vibecoded with ❤️ by [Tim Broddin](https://broddin.be) - Available for hire at [Titans of Industry](https://titansofindustry.be)*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbroddin%2Fastro-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimbroddin%2Fastro-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimbroddin%2Fastro-mcp-server/lists"}