KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

astro-mcp-server

★ 26 Open GitHub ↗

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

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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](https://raw.githubusercontent.com/TimBroddin/astro-mcp-server/main/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)*

astro-mcp-server

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README