Content
# Tarkov MCP Server
A Model Context Protocol (MCP) server that provides comprehensive access to Escape From Tarkov game
data through the [tarkov.dev](https://tarkov.dev) GraphQL API.
## Overview
This MCP server allows AI assistants to access detailed information about Escape From Tarkov,
including items, traders, maps, quests, crafting recipes, and much more. It's designed to be a
comprehensive resource for players, developers, and AI applications that need Tarkov game data.
## Features
### Available Tools
The server provides 19 different tools to access various aspects of Tarkov data:
#### Core Game Data
- **`achievement`** - Returns all achievements from Escape From Tarkov
- **`items`** - Returns comprehensive item data including stats, prices, and properties
- **`ammo`** - Returns detailed ammunition information including ballistics
- **`armor-materials`** - Returns armor material properties and durability data
#### Trading & Economy
- **`barter`** - Returns all barter trades available from traders
- **`traders`** - Returns trader information, levels, and offers
- **`flea-market`** - Returns flea market configuration and fees
#### Crafting & Hideout
- **`crafts`** - Returns all crafting recipes and requirements
- **`hideout-stations`** - Returns hideout station information and upgrades
#### Quests & Progression
- **`tasks`** - Returns all quests/tasks with objectives and rewards
- **`quest-items`** - Returns special quest-only items
- **`skills`** - Returns player skills information
- **`player-levels`** - Returns player level progression data
- **`mastering`** - Returns weapon mastering requirements
#### Maps & Locations
- **`maps`** - Returns detailed map information including extracts, spawns, and loot
- **`bosses`** - Returns boss information including health, equipment, and drops
- **`loot-containers`** - Returns loot container locations and spawn chances
- **`stationary-weapons`** - Returns stationary weapon information
#### System Information
- **`server-status`** - Returns current Tarkov server status and messages
## Installation
1. Clone this repository
2. Install dependencies:
```bash
npm install
```
3. Configure environment variables (optional):
```bash
TARKOV_API_ENDPOINT=https://api.tarkov.dev/graphql
TARKOV_LANG=en
```
## Usage
### Running the Server
```bash
npm start
```
The server will start and listen for MCP connections.
### Configuration
The server can be configured through environment variables:
- `TARKOV_API_ENDPOINT` - GraphQL API endpoint (default: https://api.tarkov.dev/graphql)
- `TARKOV_LANG` - Language code for localized content (default: en)
### Tool Details
#### achievement
Returns achievement data including:
- Achievement name and description
- Completion percentages
- Rarity information
- Side requirements (PMC/SCAV)
#### items
Returns comprehensive item data including:
- Basic properties (name, description, size, weight)
- Market prices and trends
- Item properties specific to type (weapons, armor, consumables, etc.)
- Trading information (barters, cash offers)
- Quest usage
- Crafting recipes
#### ammo
Returns ammunition data including:
- Ballistic properties (damage, penetration, accuracy)
- Armor damage and fragmentation
- Recoil and velocity modifiers
- Tracer information
#### barter
Returns barter trade information including:
- Required items and quantities
- Reward items and quantities
- Trader and level requirements
- Task unlock requirements
#### traders
Returns trader information including:
- Trader levels and requirements
- Available barters and cash offers
- Reputation levels and bonuses
- Insurance and repair rates
#### tasks
Returns quest/task data including:
- Objectives and requirements
- Rewards (items, experience, trader standing)
- Prerequisites and unlock conditions
- Map-specific information
#### maps
Returns detailed map information including:
- Spawn points and extracts
- Loot container and loose loot locations
- Boss spawn information
- Hazards and special zones
- Key requirements
#### crafts
Returns crafting recipe data including:
- Required materials and quantities
- Produced items
- Crafting station and level requirements
- Crafting duration
#### hideout-stations
Returns hideout station information including:
- Upgrade requirements (items, skills, trader levels)
- Station bonuses and effects
- Crafting capabilities
- Construction time and costs
## API Reference
All tools return data in JSON format directly from the tarkov.dev GraphQL API. The data structure
follows the GraphQL schema definitions.
### Error Handling
The server handles various error conditions:
- Network connectivity issues
- API rate limiting
- Invalid GraphQL queries
- Missing or malformed data
## Development
### Project Structure
```
src/
├── config/ # Configuration management
├── logger/ # Logging utilities
├── tools/ # MCP tool implementations
│ └── items/ # Individual tool modules
│ ├── achievements/
│ ├── ammo/
│ ├── barter/
│ └── ...
└── server.js # Main MCP server
```
### Adding New Tools
1. Create a new directory under `src/tools/items/`
2. Implement `loader.js` with GraphQL query
3. Implement `index.js` with tool definition
4. Add to `src/tools/items/index.js` exports
### Code Style
The project uses:
- ESLint for code linting
- Prettier for code formatting
Run formatting and linting:
```bash
npm run format
npm run lint
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
## Acknowledgments
- [tarkov.dev](https://tarkov.dev) for providing the comprehensive Tarkov API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- The Escape From Tarkov community for data validation and feedback
## Support
For issues and questions:
- Check the [tarkov.dev API documentation](https://tarkov.dev/api)
- Open an issue on this repository
- Join the community discussions
