YokAtlas MCP server for AI agents

This MCP server provides an interface to access YÖKATLAS (Turkish Higher Education Atlas) data using the Model Context Protocol. It allows Large Language Models (LLMs) and other clients to programmatically access program information and search functionality from the Turkish Higher Education Council's database.

Installation Requirements

Before installing the YOKATLAS MCP server, ensure your system meets these prerequisites:

Python 3.8 or newer
pip package manager (comes with Python)

Installation Steps for Claude Desktop

To use this MCP server with Claude Desktop, you'll need to install some command-line tools and the project files.

Installing uv

First, install uv, a fast Python package installer and environment manager:

For macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

For Windows (using PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternative using pip (all platforms):

pip install uv

You may need to restart your terminal or update your PATH environment variable to recognize the uv command. Verify installation with uv --version.

Installing the FastMCP CLI

Next, install the FastMCP command-line tool:

uv pip install fastmcp

Or using pip:

pip install fastmcp

Verify with fastmcp --version.

Getting the Project Files

Clone the repository to your computer:

git clone https://github.com/saidsurucu/yokatlas-mcp.git
cd yokatlas-mcp

Installing in Claude Desktop (Recommended Method)

Once you've completed the previous steps, integrate the server with Claude Desktop:

Make sure you're in the yokatlas-mcp directory containing yokatlas_mcp_server.py
Run the following command:

fastmcp install yokatlas_mcp_server.py --name "YOKATLAS API Servisi" --with yokatlas-py --with beautifulsoup4 --with setuptools --with reportlab

This command creates an isolated Python environment for your server using uv, installs the required dependencies, and registers the tool in Claude Desktop.

Manual Installation (Alternative Method)

If you prefer a manual installation:

Open Claude Desktop and go to Settings
Click on the Developer tab and click "Edit Config"
Add the following to the mcpServers section of your claude_desktop_config.json file:

"YOKATLAS API Servisi": {
  "command": "uv",
  "args": [
    "run",
    "--with", "beautifulsoup4",
    "--with", "fastmcp",
    "--with", "setuptools",
    "--with", "yokatlas-py",
    "--with", "reportlab",
    "fastmcp", "run",
    "/full/path/to/yokatlas-mcp/yokatlas_mcp_server.py"
  ]
}

Make sure to replace /full/path/to/yokatlas-mcp/yokatlas_mcp_server.py with the actual full path to the server file on your system.

Save the file and restart Claude Desktop

Available Tools

This MCP server provides the following tools:

get_associate_degree_atlas_details

Retrieves comprehensive details about a specific associate degree program for a given year.

Parameters: program_id: str, year: int

get_bachelor_degree_atlas_details

Retrieves comprehensive details about a specific bachelor's degree program for a given year.

Parameters: program_id: str, year: int

search_bachelor_degree_programs

Searches for bachelor's degree programs using various criteria.

Parameters include: uni_adi: str (university name), program_adi: str (program name), puan_turu: str (score type, e.g., SAY, EA), alt_bs: int (minimum score), ust_bs: int (maximum score), etc.

search_associate_degree_programs

Searches for associate degree programs using various criteria.

Parameters include: uni_adi: str (university name), program_adi: str (program name), alt_puan: float (minimum score), ust_puan: float (maximum score), etc.

generate_pdf_report

Creates a formatted PDF report from YOKATLAS data and saves it to your local system.

Parameters:
- data: dict - Data source (results from other YOKATLAS tools)
- report_type: str - Report type ('bachelor_search', 'associate_search', 'bachelor_details', 'associate_details')
- title: str - Report title (default: "YOKATLAS Raporu")
- language: str - Report language (currently only 'tr' is supported)
- save_to_downloads: bool - Option to save PDF to Downloads folder (default: True)

Using the PDF Report Feature

The PDF report feature allows you to transform YOKATLAS data into professional-looking PDF documents with:

Search results in organized tables
Program details structured in sections
Turkish character support
Automatic page layout and formatting
Customized formats for different result types
Information categorization
Local saving of PDF files (to Downloads folder)

Example Usage

In Claude Desktop, you can use a workflow like:

First, search for a program:

Bilgisayar Mühendisliği programlarını ara

Convert the results to a PDF and download it:

Bu sonuçları PDF rapor olarak oluştur ve indir

Or get details about a specific program and convert them to PDF:

ODTÜ Bilgisayar Mühendisliği programı hakkında detaylı bilgi ver ve PDF rapor oluştur

PDF reports will be automatically saved to your computer's Downloads folder.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "yokatlas" '{"command":"uv","args":["run","--with","beautifulsoup4","--with","fastmcp","--with","setuptools","--with","yokatlas-py","--with","reportlab","fastmcp","run","yokatlas_mcp_server.py"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "yokatlas": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "beautifulsoup4",
                "--with",
                "fastmcp",
                "--with",
                "setuptools",
                "--with",
                "yokatlas-py",
                "--with",
                "reportlab",
                "fastmcp",
                "run",
                "yokatlas_mcp_server.py"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "yokatlas": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "beautifulsoup4",
                "--with",
                "fastmcp",
                "--with",
                "setuptools",
                "--with",
                "yokatlas-py",
                "--with",
                "reportlab",
                "fastmcp",
                "run",
                "yokatlas_mcp_server.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect