VK MCP Server (ORAMAN)
VK-MCP-Server
Local MCP server for the VK API: search for people and cities, profiles, photos and video with an HTML gallery, a token pool and a SQLite cache
- 0 ★ on the repository
- Last commit
Broad access
Why this level
- VK tokens open personal data: profiles, photos, video and the friends list
- Tools for searching and collecting information about people can serve surveillance, so owner consent and an allowlist of identifiers are needed
Install
- Works in
- Services
Manual install
Install the server following `docs/INSTALLATION.md` and take the VK token from the `vk_token.txt` file without printing it. For media tools fill `VK_CONTENT_ALLOWED_IDS` only with identifiers whose owners consented.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- VK tokens open personal data: profiles, photos, video and the friends list
- Tools for searching and collecting information about people can serve surveillance, so owner consent and an allowlist of identifiers are needed
This is third-party code. Review the repository files before installing.
What it does
The Python 3.11 server runs locally and serves MCP over Streamable HTTP at `http://127.0.0.1:4257/mcp` and an HTML gallery on port 4258. The search tools `vk_search_users`, `vk_search_cities` and `vk_search_people` keep the original query in `raw_query` and show which filters were applied and which were not. Profile, education and career are read by separate tools. Media tools fetch photos, albums, video and wall posts with pagination, check the owner of every picture and drop duplicates. The result is assembled into an adaptive gallery with the tabs "Все", "Фотографии", "Видео" and "Публикации". Tokens come from a local `vk_token.txt` with rotation, answers are cached in SQLite with a 900 second TTL and a request log is kept. Content requests use the allowlist of identifiers `VK_CONTENT_ALLOWED_IDS`, and friends city statistics are enabled by a separate list `VK_FRIENDS_STATS_ALLOWED_IDS`. A system instruction for the Gemma model in Ollama and Page Assist is included.
Who it is for. Researchers and admins who work with their own VK accounts or with owner consent and run local models such as Gemma.
Good fit when
- Photos and video of your own account are collected into one gallery for viewing
- A person is searched by name with a breakdown of which filters VK applied
- A local model in Ollama connects to VK without exposing the server to the internet
- Repeated requests are cached to avoid hitting VK API limits
Not a fit when
- Collecting data about other people without their consent or a lawful basis
- The server has to be opened to the outside network: the author advises against it without separate protection and TLS
- A clear license is required: the repository intentionally has no license file
Example request
Find a person named Ivan Petrov from Kazan in VK and show the main profile, education and career.MCP
- Transport
- http
- Authentication
- API key
Environment variables
VK_TOKEN_FILE- Path to the VK tokens file, `vk_token.txt` by default.
VK_CONTENT_ALLOWED_IDS- List of identifiers for which media tools are allowed.
VK_FRIENDS_STATS_ALLOWED_IDS- List of identifiers for friends city statistics.
Limitations
Installation is described for Windows: Python 3.11 or newer, a virtual environment, `pip install -r requirements.txt`, `.env` and a `vk_token.txt` file. The server does not publish ports outward by default, and opening them without authentication and TLS is not allowed.
Media and friends statistics work only for accounts on the allowlists and other requests are rejected. Real access to VK depends on valid tokens and VK API settings, and a successful package install does not confirm it. The license is not defined by the owner, and updating through GitHub is done by `update.bat` which erases local edits on `git reset --hard`.
How to disable. Stop the `vk_mcp_server.py` process, delete `vk_token.txt` and revoke the token in VK settings, then remove the server from the client.
FAQ
How do I run VK MCP Server?
Create an environment, run `pip install -r requirements.txt`, put `vk_token.txt` next to `vk_mcp_server.py` and run `python vk_mcp_server.py`. Point the client at Streamable HTTP and `http://127.0.0.1:4257/mcp`.
For which accounts do media tools work?
Only for identifiers from `VK_CONTENT_ALLOWED_IDS`. The author advises listing your own accounts or those whose owner consented to processing.
How do I check tokens and the cache?
The `vk_token_status` and `vk_cache_status` tools show the token pool state without revealing values and the cache state. `vk_cache_clear` wipes the cache.
Is the Gemma model required?
No. The server works with any MCP client over Streamable HTTP. `GEMMA_SYSTEM_PROMPT.md` matters if you connect Gemma in Ollama or Page Assist.
What does update.bat do?
The script updates a cloned repository: it shows changes, then offers fast-forward, overwrite from the remote branch or cancel. Overwriting erases local edits.
Discussion
No questions or reviews yet.
Related
All VK toolsfull MCP for VK API
full-vk-mcp
MCP server auto-generated from the VK API schema: over 180 tools with filters by read, write, money modes and API sections
mcp-vkontakte (ailenreiko1977-tech)
mcp-vkontakte
MCP for VK on your own server: a VK API method catalog, reading walls and communities, community comparison and writes only after a human approves
MCP server for the VK API: profiles, walls, communities, photos, likes and stats, with confirmable post publishing
vk-mcp (alexfisenkov)
vk-mcp
Remote MCP server for VK communities: 50 tools, posts, comments, dialogs, photos, video and products, with writing off by default
A VK API MCP server for business: community shop, posts, ads, stats, messages and lead forms with write confirmation
An MCP server for the VKontakte wall: reading and posting, messages, friends, communities and group stats in 8 tools
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| VK MCP Server (ORAMAN) (this card) | no | API key | 0 | |
| VK MCP Server | no | API key | 16 | another VK API server without a gallery and a token pool with a cache |
| vk-mcp-ru | no | API key | 3 | a VK server without a local HTML media gallery |
README in short
The README lists the features and the delivery contents, a quick Windows install, Gemma setup, `.env` parameters, tool groups, updating through GitHub, diagnostics and security rules.